diff --git a/docs/operating-model/appendix/appendix.md b/docs/operating-model/appendix/appendix.md index d5d7eaec7..28a2b6a13 100644 --- a/docs/operating-model/appendix/appendix.md +++ b/docs/operating-model/appendix/appendix.md @@ -5,13 +5,6 @@ sidebar_position: 1 ## Role Relationships -Overview of mandatory (M) and optional (O) relationships between roles (release 23.09) - -![Role Relationships](./assets/role-relationships.png) -*Role Relationships* - -Overview of mandatory and optional relationships between roles. - | Relationship | Description | |------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | IAM-Sync | The IdP is a service responsible for storing and verifying user identities. Its objective is to enable user access to all IAMs of Catena-X operators as soon as they onboard themselves and receive a user in an IAM. Achieving this requires synchronization of each IAM with every other one, a process known as Identity-Sync, which involves both regular users and technical clients. | @@ -22,11 +15,3 @@ Overview of mandatory and optional relationships between roles. | Qualification | With the qualification, the Catena-X Association ensures that there is a uniform level of quality and service of the various providers. This creates security and trust for the users of the services. | | Trademark Rights | With the different qualifications and certifications, the respective parties receive different Catena-X labels. With these they can identify themselves and use them for illustration. The Catena-X Association holds the trademark rights to the labels and Catena-X itself | | Use | Within Catena-X, a participant can use different offers from service providers (AP, ESP, BAP). These are certified applications. Alternatively, they can certify and operate them by themselves, but then it would not use services. The offers can be SaaS solutions or local deployments. | - -## Data Exchange based on SSI - Next Steps - -**Catena-X Policies as part of the Data Exchange** -(please note the image below covers own as well as managed Wallet solutions; the credential request flow is not displayed since no changes are planned so far) - -![Further development of the data exchange based on SSI](./assets/further-development-of-the-data-exchange-based-on-ssi.png) -*Further development of the data exchange based on SSI* diff --git a/docs/operating-model/appendix/assets/further-development-of-the-data-exchange-based-on-ssi.png b/docs/operating-model/appendix/assets/further-development-of-the-data-exchange-based-on-ssi.png deleted file mode 100644 index e40578c7e..000000000 Binary files a/docs/operating-model/appendix/assets/further-development-of-the-data-exchange-based-on-ssi.png and /dev/null differ diff --git a/docs/operating-model/appendix/assets/role-relationships.png b/docs/operating-model/appendix/assets/role-relationships.png deleted file mode 100644 index 7864af88e..000000000 Binary files a/docs/operating-model/appendix/assets/role-relationships.png and /dev/null differ diff --git a/docs/operating-model/change-log/_category_.json b/docs/operating-model/changelog/_category_.json similarity index 72% rename from docs/operating-model/change-log/_category_.json rename to docs/operating-model/changelog/_category_.json index 02d96e7a7..f486277c4 100644 --- a/docs/operating-model/change-log/_category_.json +++ b/docs/operating-model/changelog/_category_.json @@ -1,5 +1,5 @@ { - "label": "Change Log", + "label": "Changelog", "position": 12, "collapsible": true, "collapsed": true diff --git a/docs/operating-model/change-log/change-log.md b/docs/operating-model/changelog/changelog.md similarity index 57% rename from docs/operating-model/change-log/change-log.md rename to docs/operating-model/changelog/changelog.md index 087c4070b..75879ce50 100644 --- a/docs/operating-model/change-log/change-log.md +++ b/docs/operating-model/changelog/changelog.md @@ -1,9 +1,38 @@ --- sidebar_position: 1 +sidebar_class_name: separator-top --- -# Change Log +# Changelog -## Added +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +## [3.0.0] + +### Added + +- Introduction + - Data Space interoperability (basic technical, semantic, legal, organizational criteria for interoperability with Catena-X) +- Roles + - Sandbox Provider [BETA] +- Governance: + - New Labels (Qualified Advisor, Qualified Company) + - Data exchange contracts, ODRL-policies, Country Clearance List + - Enforcement of compliance with normative documents (e.g. sanctions) + +### Changed + +- Roles + - OSP updated and enabled +- Overview & Service Map + - Industry Core and Knowledge Agent incl. updated Data Ecosystem depiction updated +- Operations + - Update SSI 2.0, Identity and Trust Protocol (IATP) and Issuer Authority updated +- Governance + - Update Release Management (e.g. release management process, backwards compatibility) updated + +## [2.1.0] + +### Added - Role: Catena-X Automotive Network e.V. - Service Map: Onboarding Service Category @@ -20,7 +49,7 @@ sidebar_position: 1 - Qualification Process - Exceptions -## Changed/Updated +### Changed - Introduction: clarity and readability improvements - Roles: @@ -31,7 +60,3 @@ sidebar_position: 1 - Certification process: reference provided to Conformity Assessment Framework that details the Catena-X certification process further - Labels: Removed distinguishing factors between Certified Operating Company and Certified Partner - Outlook: updated according to release 23.09 - -## Unchanged - -- Nomination Process diff --git a/docs/operating-model/glossary/glossary.md b/docs/operating-model/glossary/glossary.md index a07f0c654..699fca3ed 100644 --- a/docs/operating-model/glossary/glossary.md +++ b/docs/operating-model/glossary/glossary.md @@ -35,3 +35,4 @@ sidebar_position: 1 | OSP | Onboarding Service Provider | | VC | Verifiable Credential | | VP | Verifiable Presentation | +| STS | Secure Token Service | diff --git a/docs/operating-model/how-data-space-governance/assets/Certification.png b/docs/operating-model/how-data-space-governance/assets/Certification.png new file mode 100644 index 000000000..fb9df0cc0 Binary files /dev/null and b/docs/operating-model/how-data-space-governance/assets/Certification.png differ diff --git a/docs/operating-model/how-data-space-governance/assets/Governance-for-Non-Technical-Requirements.png b/docs/operating-model/how-data-space-governance/assets/Governance-for-Non-Technical-Requirements.png new file mode 100644 index 000000000..5780e9257 Binary files /dev/null and b/docs/operating-model/how-data-space-governance/assets/Governance-for-Non-Technical-Requirements.png differ diff --git a/docs/operating-model/how-data-space-governance/assets/catena-x-add-solutions-and-participants-to-the-whitelist.png b/docs/operating-model/how-data-space-governance/assets/catena-x-add-solutions-and-participants-to-the-whitelist.png new file mode 100644 index 000000000..35d760ba8 Binary files /dev/null and b/docs/operating-model/how-data-space-governance/assets/catena-x-add-solutions-and-participants-to-the-whitelist.png differ diff --git a/docs/operating-model/how-data-space-governance/assets/how-data-space-governance.pptx b/docs/operating-model/how-data-space-governance/assets/how-data-space-governance.pptx new file mode 100644 index 000000000..6b742b3aa Binary files /dev/null and b/docs/operating-model/how-data-space-governance/assets/how-data-space-governance.pptx differ diff --git a/docs/operating-model/how-data-space-governance/assets/modular_system1.png b/docs/operating-model/how-data-space-governance/assets/modular_system1.png new file mode 100644 index 000000000..2e2113f03 Binary files /dev/null and b/docs/operating-model/how-data-space-governance/assets/modular_system1.png differ diff --git a/docs/operating-model/how-data-space-governance/assets/modular_system2.png b/docs/operating-model/how-data-space-governance/assets/modular_system2.png new file mode 100644 index 000000000..fbfbaba3b Binary files /dev/null and b/docs/operating-model/how-data-space-governance/assets/modular_system2.png differ diff --git a/docs/operating-model/how-data-space-governance/how-data-space-governance.md b/docs/operating-model/how-data-space-governance/how-data-space-governance.md index 9444b214c..3bf835dca 100644 --- a/docs/operating-model/how-data-space-governance/how-data-space-governance.md +++ b/docs/operating-model/how-data-space-governance/how-data-space-governance.md @@ -15,7 +15,7 @@ However, this vision is complex: companies at various stages of the automotive v The standards of our Catena-X data ecosystem define how the exchange of data and information in our network works. They are the basis for ensuring that the technologies, components, policies, and processes used are developed and operated according to uniform rules. All standards developed for the Catena-X data ecosystem are based on the technological and industry-specific requirements of the automotive industry. -The Catena-X Association publishes standards for generic core and enabling services as well as for domain-specific business applications (see KITs Chapter [KITs – Keep It Together](./../what-service-map/what-service-map.md#kits--keep-it-together)). These standards and artifacts form the basis for the development and operation of software components in the Catena-X network to ensure interoperability and data sovereignty between different software components and providers. All relevant standards are accessible in the [Catena-X standard library](https://catena-x.net/de/standard-library). +The Catena-X Association publishes standards for generic core and enabling services as well as for domain-specific business applications (see KITs Chapter [KITs – Keep It Together](./../what-service-map/what-service-map.md#kits--keep-it-together)). These standards and artifacts form the basis for the development and operation of software components in the Catena-X network to ensure interoperability and data sovereignty between different software components and providers. All relevant standards are accessible in the [Catena-X standard library](https://catenax-ev.github.io/docs/standards/overview). ### How do we standardize? @@ -24,17 +24,17 @@ Based on [Catena-X’s Intellectual Property(IP)-Regulations](https://catena-x.n ![Catena-X Standardization Process](./assets/catena-x-standardization-process.png) *Catena-X Standardization Process* -The [Catena-X standardization policy](https://catena-x.net/en/catena-x-introduce-implement/standardisierung) provides a detailed description of how Catena-X standards are being developed including everyone involved and their respective responsibilities. +The [Catena-X Website](https://catena-x.net/en/catena-x-introduce-implement/standardisierung) provides a detailed description of how Catena-X standards are being developed including everyone involved and their respective responsibilities. -## Conformity Assessment +## Conformity Assessment and Certification ### Why do we certify? -Cross company interactions highly rely on mutual trust. Our certifications provide trust via transparency and reliability based on our Catena-X standards. By setting up a certification process, we guarantee that our major principles are considered in every component of the network. From the core service providers to the data connectors and every single application in the network, a consistent framework was created to ensure beneficial participation for all participants in the network. A chain is only as strong as its weakest link, and to gain trust we need to ensure that all links are as strong as possible. +Cross company interactions highly rely on mutual trust. Catena-X issues certifications in order to provide trust via transparency and reliability based on our Catena-X standards. By setting up a certification process, we guarantee that our major principles are considered in every component of the network. Independent of size and role, core service providers or small application, a consistent framework was created to ensure beneficial participation for all participants in the network. A chain is only as strong as its weakest link, and to gain trust we need to ensure that all links are as strong as possible by encouraging the consistent use of standards and providing a quality label to those who do. ### What do we certify? -Catena-X certification is done in a modular, role-based way, to fulfill different requirements of participants in our ecosystem, whether IT application providers, service providers or onboarding partners. The modularity allows high flexibility and lowers the efforts and redundancies for all parties involved. Catena-X standards become mandatory for certification as soon as they have been integrated into the certification framework. The Catena-X Association aims to release an update of its certification framework simultaneously with newly released standards. The most current version can always be found on the [Catena-X website](https://catena-x.net/en/catena-x-introduce-implement/certification). +Catena-X certification is done in a modular, role-based way, to fulfill different requirements of participants in our ecosystem, whether IT application providers, service providers or onboarding partners. The modularity allows high flexibility and lowers the efforts and redundancies for all parties involved. The certification framework details all standards a company has to comply with based on their role, the goal of their service and the use-case in which they participate e.g. PLM & Quality, Sustainability, Resiliency. Catena-X standards become mandatory for certification as soon as they have been integrated into the certification framework. The Catena-X Association aims to release an update of its certification framework simultaneously with newly released standards. The most current version can always be found on the [Catena-X website](https://catena-x.net/en/catena-x-introduce-implement/certification). ### How do we certify? @@ -42,45 +42,80 @@ An overview of the certification process is depicted in Figure [Catena-X Certifi ![Catena-X Certification Process](./assets/catena-x-certification-process.png) *Catena-X Certification Process* -The [Catena-X Conformity Assessment Framework Handbook](https://catena-x.net/en/catena-x-introduce-implement/certification) provides a detailed description of how Catena-X conducts conformity assessment through Conformity Assessment Bodies. +The *Catena-X Conformity Assessment Handbook* provides a detailed description of how Catena-X conducts conformity assessment through Conformity Assessment Bodies. The most current version can always be found on the [Catena-X website](https://catena-x.net/en/catena-x-introduce-implement/certification). ### Catena-X Labels -Catena-X issues four different labels to help customers find suitable and legitimate providers for their needs. Each label is issued to the relevant role after achieving successful certification and/or qualification. Labels are associated with the offered services of the provider. +Catena-X issues four different labels to indicate a company has been successfully certified or qualified and is compliant with Catena-X standards. This is in order to help customers find suitable and legitimate providers who have been assessed to comply with Catena-X standards or qualification requirements. +Each label is issued to the relevant role after achieving successful certification and/or qualification. Labels are associated with the offered services of the provider as stated in the certification framework on the [Catena-X website](https://catena-x.net/en/catena-x-introduce-implement/certification). -**Certified Operating Company** (CSP-A/CSP-B) +**Certified Operating Company** ![Certified Operating Company](./assets/certified-operating-company.png) -**Certified Provider** (e.g., BAP, ESP, OSP) +Certified operating companies are companies certified for operating core services in the Catena-X ecosystem. + +**Certified Provider** ![Certified Provider](./assets/certified-provider.png) -**Certified Solution** (e.g., Business App, Service….) +“Provider” is defined by standards for the general participation in the data ecosystem depending on their role. +The standards include but are not limited to the following standard types: International standards (e.g., ISO 27001), Catena-X Standards and Rules, Service-Level Agreements. This role can be obtained e.g. by an ESP, BAP or OSP. + +**Certified Solution** ![Certified Solution](./assets/certified-solution.png) -**Qualified Advisor** (Advisory Provider) +“Solution” is defined by standards that focus on executable software based on business domain or platform capabilities and includes but is not limited to: Application Logic, Application Programming Interface Specification,  Data Access (e.g., usage policies), Payload or Meta-Data, Processes (e.g., onboarding process), Business Logic (e.g., PCF Rulebook), Consulting Offerings, Conformity Assessment Requirements + +Certified solutions specifically refers to the solutions certified. + +**Qualified Advisor** (Advisory Provider) ![Qualified Advisor](./assets/qualified-advisor.png) -Each label is obtained after successful completion of the Catena-X certification or qualification process. Details on pathways to be added. +Qualified Advisor refers to the individual advisor qualified for advisory services related to the Catena-X data space and its use. If a company has more than 5 Qualified Advisors, they can also use the label at company level. + +#### Scope of Labels + +Labels are only to be used upon a successful completion of the certification/ qualification process. The type of certification process conducted is subject to the assessment of the CAB. The type of qualification process conducted is subject to the assessment of the Catena-X association. Certificates are bound to an ecosystem release, e.g. Jupiter and expire the moment, an ecosystem release is outdated (lifecycle state = deprecated). To maintain a valid label, a certification for one of the subsequent ecosystem releases has to be completed. The use of older terminologies and visuals are not permitted and are therefore to be phased out within a transition period of three months since the latest release of this document, Catena-X Operating Model. Furthermore, companies shall solely use the name of the label for their role (certified operating company/ certified provider/ certified solution) as specified in the Catena-X Certification Framework. +Companies or advisors are solely liable for providing the services. The certification does not provide any warranties of the quality of the work and the services of the certified companies or qualified advisor. In order to verify the validity of a provider at hand, please refer to the official list of certified providers on the [Catena-X website](https://catena-x.net/en/catena-x-introduce-implement/certification). + +#### Guidelines of Label Use + +Any official Catena-X label can be downloaded from the [Catena-X repository](https://github.com/catenax-eV/cx-resources). The labels are to be used in their original design only. Changes to the label, the wording, or the color scheme shall not be conducted. In any communication, the label is to be referred to with the term “Catena-X certified" or "Catena-X qualified” only. The term is exclusive to Catena-X certified companies or Catena-X qualified advisors. -### Exceptions & Timeline for Release 23.09 +### Certification framework -Release 23.09 is the official GoLive Release of the Catena-X data ecosystem. For the first time, all major components of the Catena-X data ecosystem will be available to the vast majority of the automotive value chain. To fulfil this promise to all our stakeholders while some areas of Catena-X are still under development, certain exceptions are made during this transitional period: +Certifications and qualifications at Catena-X can be obtained for different types of services or solutions. The certifications are split into different "roles" indicating the type of relationship to Catena-X, as well as the"module", the specific service provided. The roles of certified companies vary between the provision of a key part of infrastructure or service ( Enablement Service Provider or Core Service provider) and complementing further solutions or services to the data space. In line with this role differentiation, the certifications have a different scope and different Catena-X standards associated with them. + Companies shall always mention the specific role and module they have been awarded the certification in e.g. Connector, Traceability, MaaS... . -#### 1. 45-day grace period to obtain valid certification after Release 3.2 (23.09) +![Certification](./assets/Certification.png) +*Certification System* -Catena-X will release a standard update (Release 3.2) on Sept. 28, 2023, on the Catena-X Association website. **This release will include “breaking changes” as defined in the** [Semantic Versioning](https://semver.org/). + The following figure details the standards applicable to each of the six roles and matching modules. -The GoLive of the Catena-X data ecosystem (productive environment) will be **exclusively on Release 3.2**. This will be accompanied by an **update of the certification framework** (“which role needs to have which components certified”) for release 3.2. +![Modular System1](./assets/modular_system1.png) -Each partner needs to ensure conformity to the new standards to be active in the data space. To this end, the following procedure applies: Every participant in the data space has **45 days after Sept. 28** (grace period) to complete their certification via a CAB or, in case of an existing certification, via free self-assessment. **Deadline is Nov. 12, 2023** (Sept. 28 + 45 days). +![Modular System2](./assets/modular_system2.png) -Cofinity-X will **allow data space registration** of a partner from GoLive Oct. 16 after consultation with the Association, **subject to the proviso that certification must be completed by the Nov. 12 deadline**. If the certificate is not proven within the 45 days, Partners must be removed from the data space at the direction of the Catena-X Association. +### Certification updates -Data space participants and their solutions that were already certified for Release 3.0/3.1 can use the 45-day grace period to prove their compliance to the Association via a **free self-assessment** and thus confirm the validity of their certificate even after release updates (up to a maximum of 12 months after initial issue). A corresponding form including confirmation of conformity with each standard required for the certificate can be requested from [info@catena-x.net](mailto:info@catena-x.net). This does not apply to a CSP-B. +Each certified partner needs to ensure conformity to the standards to be active in the data space. Every certified participant in the data space has the obligation to remain compatible with at least one of the supported ecosystem releases through certification via a CAB. If there is no valid certificate after the ecosystem release tied to the respective certificate expires, Partners lose the status of certification/ qualification and are no longer listed as such on the Data Space Clearance List after the above mentioned 120 days of grace period expire. Each label is obtained after successful completion of the Catena-X certification or qualification process. + +### Further clarifications for Release Jupiter + +Jupiter is the next ecosystem release of the Catena-X data ecosystem. For the first time, all major components of the Catena-X data ecosystem will be updated for all active and future users of the network. To offer a smooth transition to all our stakeholders to a new major release, certain measures are taken during the transitional period: + +#### 1. Self-Assessment to maintain valid certification after Release 24.05 + +Catena-X will release a standard update (Preview Jupiter) in June 2024, on the Catena-X Association website. **This release will include “breaking changes” as defined in the** [Semantic Versioning](https://semver.org/). + +The productive environment of the Catena-X data ecosystem (productive environment) will be **exclusively on Release Jupiter**. This will be accompanied by an **update of the certification framework** (“which role needs to have which components certified”). + +Each partner needs to ensure conformity to the new standards to be active in the data space. To this end, the following procedure applies: Every participant in the data space has until **October 2024** (grace period) to complete their certification via a CAB or, in case of an existing certification, via free self-assessment. If there is no valid certificate for Jupiter, Partners must be removed from the data space at the direction of the Catena-X Association as of October 16th 2024. + +Data space participants and their solutions that have a valid certificate past October 2024 can use the period between the standard update in June 2024 and the industrialization of Jupiter via the Operating Company to prove their compliance to the Association via a **free self-assessment** and thus confirm the validity of their certificate even after release updates (up to a maximum of 12 months after initial issue). A corresponding form including confirmation of conformity with each standard required for the certificate can be requested from [info@catena-x.net](mailto:info@catena-x.net). #### 2. Certification of business applications vs. internal systems that fall under the definition of a Catena-X business application* -**A business application** provides specific logic and schemas defined in a Catena-X use case (e. g., data processing, transformation functions) that is applied to input data to produce an expected output. This includes the transformation of data from an input format into an output format using Catena-X semantic models (semantic interoperability) as well as the technical data exchange using standardized protocols and API-specifications (technical interoperability). This does not apply to internal systems of an organization, such as internal databases, data lakes, data pipelines (ETL) or source systems. To become operational on the Catena-X data space, a business application must comply with the corresponding standards (see Chapter [Increase Decentralization of Core Services](./../outlook/outlook.md#increase-decentralization-of-core-services)). +**A business application** provides specific logic and schemas defined in a Catena-X use case (e.g., data processing, transformation functions) that is applied to input data to produce an expected output. This includes the transformation of data from an input format into an output format using Catena-X semantic models (semantic interoperability) as well as the technical data exchange using standardized protocols and API-specifications (technical interoperability). This does not apply to internal systems of an organization, such as internal databases, data lakes, data pipelines (ETL) or source systems. To become operational on the Catena-X data space, a business application must comply with the corresponding standards. Companies connected to Catena-X might want to **connect certain internal systems** including company-internal business applications to the Catena-X network. It remains, however, crucial that all participants can rely on a standardized data exchange that guarantees stable data chains built on data sovereignty and interoperability. @@ -91,16 +126,13 @@ Consequently, the following two principles apply: If an internal system fulfills one of these two criteria, a Catena-X certification is mandatory. -*For future reference, to provide a scalable way of certification, additional technical and partially automated solutions -of assessing conformity are currently under assessment. (10 votes for, 0 against à also Steve vote for publication) - -#### 3. No Catena-X Business Applications without listing on a certified CX Marketplace +#### 3. No Catena-X Business Applications without listing on a certified Catena-X Marketplace -Catena-X is built on trust. Consequently, certified Catena-X marketplaces (CSP-A) are checking, whether services provided are coming with verified credentials to ensure that the listed offer is trustworthy and conform to Catena-X standards. +Catena-X is built on trust. Consequently, certified Catena-X marketplaces (CSP-A) are checking, whether services are certified to ensure that the listed offer is trustworthy and conform to Catena-X standards. -To further anchor this trust, all Catena-X related business applications and services require a listing on a Catena-X certified marketplace. Catena-X does not permit operating a Catena-X solution outside of a certified Catena-X market place. +To further anchor this trust, all Catena-X related business applications and services require a listing on a Catena-X certified marketplace. Catena-X does not permit operating a Catena-X solution outside of a certified Catena-X marketplace. -As noted in Chapter [Increase Decentralization of Core Services](./../outlook/outlook.md#increase-decentralization-of-core-services), as of release 23.12, Catena-X will provide the technical possibility for multiple CSP-A providers. This will foster multiple verifiers of credentials. +As noted in Chapter [Increase Decentralization of Core Services](./../outlook/outlook.md#increase-decentralization-of-core-services), Catena-X will provide the technical possibility for multiple CSP-A providers. This will foster multiple verifiers of credentials. ## Nomination Process for unique Roles (e.g., CSP-B) @@ -117,9 +149,9 @@ The process steps of the nomination process are described in detail below. | Create Request for Tender (RfT) | The Catena-X Association is responsible for the creation of the Request for Tender (RfT) document (e.g., for Core Services - section B) | | RfT Document(s) | | Publish RfT on Website | The Catena-X Association is responsible for the publication and distribution of the [RfT Document on the website](https://catena-x.net/en/). | RfT Document(s) | RfT Document(s) RfT Event incl. Timeline RfT Template | | Create and Submit Tender for selected Core Service(s) | A provider can create and submit a tender for the published RfT. | RfT Document RfT Event RfT Template | Tender | -| Receive and Review Submissions | The CX Association compares the tender(s), regarding the fulfillment of the nomination criteria and creates a short list of candidates for the board. | Tender(s) | Short List of Provider Candidates | +| Receive and Review Submissions | The Catena-X Association compares the tender(s), regarding the fulfillment of the nomination criteria and creates a short list of candidates for the board. | Tender(s) | Short List of Provider Candidates | | Select Provider | The board of the Association elects a provider with an absolute majority vote. | Short List of Provider Candidates | Nomination of Provider | -| Inform Providers | The CX Association informs all provider(s) about the result of the nomination process. | | | +| Inform Providers | The Catena-X Association informs all provider(s) about the result of the nomination process. | | | ## Qualification Process @@ -127,7 +159,7 @@ The process steps of the nomination process are described in detail below. On the way to creating value with Catena-X, companies may be dependent on advisory services. The quality of these advisory services is decisive for the success of the participation and thus for the success of Catena-X. Catena-X can only be successful if it succeeds in integrating large parts of the automotive value chain. We assume that this will lead to a high demand for advisory services, which must be met. These advisory services must cover the needs of small and medium-sized companies as well as the needs of large companies, which have extended integration requirements. -Advisory services are hard, if not impossible, to standardize. Consequently, conformity assessment of qualified advisory services cannot take place through certification. To maintain a consistent level of quality among advisory service providers in the Catena-X data space, the Catena-X Association thus offers a qualification process that is mandatory for all advisory service providers that want to get listed in a marketplace. Advisory service providers, like all other participants active on the Catena-X data space, must adhere to the Catena-X regulatory framework and thereby confirm their full and unconditional support of our data ecosystem including its mission and standards. +Advisory services are hard, if not impossible, to standardize. Consequently, conformity assessment of qualified advisory services cannot take place through certification. To maintain a consistent level of quality among advisory service providers in the Catena-X data space, the Catena-X Association thus offers a qualification process that is mandatory for all advisory service providers who want to get listed in a marketplace. Advisory service providers, like all other participants active in the Catena-X data space, must adhere to the Catena-X regulatory framework and thereby confirm their full and unconditional support of our data ecosystem including its mission and standards. ### Who do we qualify? @@ -145,13 +177,132 @@ For most advisory service providers, the first option applies. Qualification thr ![Catena-X Qualification Process](./assets/catena-x-qualification-process.png) *Catena-X Qualification Process* -As of the Operating Model White Paper v.2.1, the process for qualification through training has yet to be established. It will be released on the Catena-X website as soon as it is available. Qualification through experience applies to all advisory service providers that registered for and participated in the Catena-X beta phase. If a company is interested in qualification and/or the proof of qualification, the first step is to contact the Catena-X Association via [info@catena-x.net](mailto:info@catena-x.net). Further information and a first questionnaire to collect basic information about the company will then be made accessible. +As of the Operating Model White Paper v.3, the process for qualification through training has yet to be established. It will be released on the [Catena-X website](https://catena-x.net/en/catena-x-introduce-implement/advisory-ecosystem) as soon as it is available. Qualification through experience applies to all advisory service providers that registered for and participated in the Catena-X beta phase. If a company is interested in qualification and/or the proof of qualification, the first step is to contact the Catena-X Association via [onboardingcommittee@catena-x.net](mailto:onboardingcommittee@catena-x.net). Further information and a first questionnaire to collect basic information about the company will then be made accessible. + +## Guidelines of qualification use + +Different from Catena-X Certification, Catena-X qualification is a label held by an individual. Individuals passing the assessment process and being awarded the title "Qualified Advisor" may refer to themselves as "Catena-X qualified". Companies with more than 5 employees with this qualification may refer to their entire company as "Catena-X qualified". ## Regulatory Framework -The [Catena-X Regulatory Framework for data space operations](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations) outlines the requirements and responsibilities for all stakeholders involved in the Catena-X data ecosystem. It includes detailed information on data sovereignty, mandatory use case requirements, and other regulatory considerations that are relevant and mandatory to our activities. The Regulatory Framework is made up of individual components that each govern a specific layer of our data space operations. To understand the layers of our Regulatory Framework, Catena-X uses flight levels as a metaphor (see Figure [Catena-X Governance Framework flight levels](./how-data-space-governance.md#regulatory-framework)): +The [Catena-X Regulatory Framework for data space operations](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations) outlines the **non-technical requirements** and responsibilities for all stakeholders involved in the Catena-X data ecosystem. It includes detailed information on data sovereignty, mandatory use case requirements, and other regulatory considerations that are relevant and mandatory to our activities. The Regulatory Framework is made up of individual components that each govern a specific layer of our data space operations. To understand the layers of our Regulatory Framework, Catena-X uses flight levels as a metaphor (see Figure [Catena-X Governance Framework flight levels](./how-data-space-governance.md#regulatory-framework)): ![Catena-X Governance Framework flight levels](./assets/catena-x-governance-framework-flight-levels.png) *Catena-X Governance Framework flight levels* -Each higher-level cascades into the lower ones, and the lower levels align with those above. Each level comes with specific guidelines and resources but also responsibilities for participants in our data space. This Operating Model falls under the 30,000 ft level and is thus mandatory for all data space participants. Maintaining and updating our Regulatory Framework for data space operations lies within the responsibility of the Catena-X Association. All resources and normative documents included in the regulatory framework are listed on the [Catena-X website](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations). +Each higher level cascades into the lower ones, and the lower levels align with those above. Each level comes with specific guidelines and resources but also responsibilities for participants in our data space. This Operating Model falls under the 30,000 ft level and is thus mandatory for all data space participants. Maintaining and updating our Regulatory Framework for data space operations lies within the responsibility of the Catena-X Association. All resources and normative documents included in the regulatory framework are listed on the [Catena-X website](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations). + +### Concluding Data Exchange Contracts via Catena-X + +The Catena-X Data Space enables Data Providers and Data Consumers to conclude data exchange contracts via registered connectors. + +While Data Providers and Data Consumers have the option of concluding bilateral contracts (supplier contract, ...) outside of a registered connector to determine their contractual relationship for data exchange via Catena-X, the Catena-X Regulatory Framework sets out certain boundary conditions (10 Golden Rules, Data Exchange Governance...) that are binding for all data space participants and cannot be negated with bilateral contracts outside the confines of the Catena-X Regulatory Framework. + +These boundary conditions, combined with the possibility to automate data exchange contract negotiations, form one of the key benefits and foundations for scaling of the Catena-X Data Space. For more information on how to conclude data exchange contracts via Catena-X, please refer to the [Catena-X memorandum on how to conclude data exchange contracts](https://catena-x.net/fileadmin/user_upload/04_Einfuehren_und_umsetzen/How_To_Conclude_Data_Exchange_Contracts.pdf). + +### Standardized modules for data exchange contracts + +The Catena-X Association aims to develop further automation and scalability of the process of concluding data exchange contracts via Catena-X. Connectors will enable Participants to choose from a range of modules when negotiating and agreeing on terms within the Data Exchange Governance (e.g. liability/dispute resolution/choice of law etc.). All official modules provided by the Catena-X Association are listed under the official [Catena-X Open Digital Rights Language Repository](https://github.com/catenax-eV/cx-odrl-profile). + +As of Release 24.05., these modules are limited to standardized data usage policies for Catena-X use cases. + +### Governance for Non-Technical Requirements + +Standardized contractual modules, as all parts of the Catena-X Regulatory Framework, are categorized as so-called **Non-Technical Requirements** (vs. technical requirements = **standards**). All Non-Technical Requirements are not subject to the technical Catena-X standardization process, governed by the Catena-X Technical Committee for Standardization, but are rather developed under the auspices of the formally responsible Committee (e.g. Catena-X Data Space Operations Committee for standardized contractual modules) and are formally approved by the Catena-X Management Board. This process mirrors the technical standardization process in order to provide accessibility, transparency and ease of understanding and differs mainly in the actors involved as governing bodies. + +A general overview of the process is depicted in Figure [Catena-X process for Non-Technical Requirements](./how-data-space-governance.md#governance-for-non-technical-requirements): + +![Catena-X process for Non-Technical Requirements](./assets/Governance-for-Non-Technical-Requirements.png) +*Catena-X process for Non-Technical Requirements* + +### Country clearance list + +The Catena-X association issues a [country clearance list](https://catena-x.net/fileadmin/user_upload/04_Einfuehren_und_umsetzen/Governance_Framework/Catena-X_-_Country_Clearance_list.pdf) that specifies countries, in which companies can be onboarded to the Catena-X data space. This list acts as mandatory guidance to all OSPs for registering participants in the Catena-X data space. + +In the same document, the Catena-X association includes countries currently under clearance review. An onboarding of companies from this category is only possible after a due diligence check, followed by separate approval by the Catena-X association. A request for such a due diligence check can be requested by any OSP to the Catena-X association under [info@catena-x.net](mailto:info@catena-x.net). + +## Enforcement of compliance with normative documents + +An effective governance model requires clear guidelines and enforcement mechanisms to ensure that all participants comply with the agreed normative documents. This chapter focuses on how the Catena-X association proceeds if participants violate the rules and guidelines set out in the Catena-X governance framework. It describes the processes and measures that are taken to ensure compliance and to ensure that the trust and integrity of the network are maintained. + +### How do we monitor violations? + +The following chapter describes how monitoring generally takes place and what categories there are. The exact implementation can be found in chapter [Implementation and set-up](./how-data-space-governance.md#implementation-and-set-up). + +**Active Monitoring** +Active monitoring encompasses proactive measures to detect and address potential violations promptly. This involves checks of certificates within the network and among participants, and regular feedback collection from OSPs, CSPs and CABs regarding the certification status of their users. By actively engaging in these monitoring activities, the Catena-X community can swiftly identify deviations from established normative documents and take corrective actions to maintain compliance. + +**Passive Monitoring** +In addition to active oversight, the Catena-X Association provides a passive monitoring gateway where participants can report violations within the Catena-X data space. This point of contact serves as a confidential channel for data space participants to raise concerns or flag instances of non-compliance observed within the ecosystem. By fostering a culture of accountability and transparency, Catena-X encourages all stakeholders to actively participate in upholding the integrity of the data space. + +### What are the consequences of such violations? + +**Withdrawal of Certificates and Certification** +At the foundational level, non-compliant participants face the withdrawal of their certificates and certification status. This action signifies the removal of official recognition for adhering to Catena-X standards, signaling a loss of credibility within the ecosystem. Furthermore, it limits the actions of the given party. Without a certificate, it's e.g. no longer possible to provide business apps as a BAP or participate in a use case as a DPC. + +**Exclusion from Data Space Clearance List and Data Space Access** +Participants found in violation of normative documents may be excluded from the Catena-X Data Space Clearance List, effectively barring them from accessing the data space and limiting their ability to engage in data exchange activities within the Catena-X data space. Further details about the Data Space Clearance List can be found in chapter [Implementation and set-up](./how-data-space-governance.md#implementation-and-set-up). + +Depending on the nature and severity of the violation, a combination of consequences may be applied to address the non-compliance effectively. The Catena-X Association is further developing the consequences described and investigating further possibilities. Details can be found in the chapter [outlook](./../outlook/outlook.md#enforcement-of-compliance-with-normative-documents). + +### Implementation and set-up + +As described in Chapter [How do we monitor violations](./how-data-space-governance.md#how-do-we-monitor-violations), there are two input channels on which the Catena-X Association can receive various information. + +#### Active Monitoring + +For active monitoring, there is a public list showing all certified parties and apps. This list can be found [Certified Catena-X Solutions & Participants](https://catenax-ev.github.io/). This list of certified parties and solutions is updated by two roles: + +##### OSP - Onboarding Service Provider + +The OSP enables and supports data space participants to register, onboard and offboard to the Catena-X data space. The OSP is required to add every company successfully onboarded to the productive Catena-X data space in the Catena-X data space clearance list. This ensures, that the Data Space Clearance List contains all data space participants regardless by which OSP they were onboarded. + +##### CAB - Conformity Assessment Body + +The CAB is responsible for adding all certificates that are being issued to the list. This provides a clear overview of solutions that are certified and who got certified. On the one hand, this creates a clear overview of all solutions certified by Catena-X and on the other hand also the possibility of comparing whether a participant offers a solution that is still certified. + +##### Data Space Clearance List - Certified Catena-X Solutions & Participants + +The following figure shows the process of how OSPs & CABs can add the various participants or solutions to the Data Space Clearance List. + +![Catena-X data space clearance list process](./assets/catena-x-add-solutions-and-participants-to-the-whitelist.png) +*Catena-X Data Space Clearance List process* + +| Process Step | Description | Input | Output | +|-------------------------------------|----------------------------------------------------------------------------------------------------------------------------|----------------------|--------------------| + +| successful onboarding/certification | The CAB or OSP is responsible for providing the mandatory data within 5 working days | | data provided | +| Review data for completeness | Review if all the mandatory data is provided and if the format is correct | data from CAB or OSP | | + +| Formal Check | Review of content by the dataspace operations committee if the provided data is valid | | | +| Decision | Final approval to add data to data space clearance list, in case of deny - feedback is provided and CAB or OSP must crete a new request | | Approval or denial | + +In order to obtain a simple overview of the various entries as well as an overall overview of the data space, various additional attributes are added to an entry. The data that an entry receives is as follows: + +- Name of Legal Entity incl. BPNL + - Roles [List - could be multiple] + - Date of onboarding + - Name of OSP incl. BPNL + - If the Company has a certificate + - Date of issue + - Expiry date + - Version against which was certified + - Type of Certificate [OR] + - Use Case [Sustainability [PCF, Circularity], Traceability, Quality, DCM, BPDM VAS] + - Infrastructure [Enablement Service, Onboarding Service] + - If the company is qualified + - Date of issue + - Expiry date + - Type of Qualification [OR] + - Experience + - Qualification Process + +#### Passive Monitoring + +To ensure that the Catena-X association has the opportunity to investigate and record information from each party in the data space at any time, there is a confidential option to provide this to the association. For this purpose, the association offers a dedicated mailbox, which can be reached at the following E-Mail [info@catena-x.net](mailto:info@catena-x.net). The process for handling these requests is still being worked out. Details can be found in the chapter [Outlook](./../outlook/outlook.md#enforcement-of-compliance-with-normative-documents). + +### Limitations + +With this version of the operating model we will only establish the process (e.g. add Solutions and participants to the Data Space Clearance List) and tools (e.g. Data Space Clearance List) mentioned above. The consequences of violations, as described in the chapter [What are the consequences of such violations](./how-data-space-governance.md#what-are-the-consequences-of-such-violations), will be further refined and elaborated upon. + +Further details can be found in the chapter [Outlook](./../outlook/outlook.md#enforcement-of-compliance-with-normative-documents). diff --git a/docs/operating-model/how-data-space-operations/assets/data-exchange-process.png b/docs/operating-model/how-data-space-operations/assets/data-exchange-process.png index ecf333657..ff7d9e581 100644 Binary files a/docs/operating-model/how-data-space-operations/assets/data-exchange-process.png and b/docs/operating-model/how-data-space-operations/assets/data-exchange-process.png differ diff --git a/docs/operating-model/how-data-space-operations/assets/general-onboarding-process.png b/docs/operating-model/how-data-space-operations/assets/general-onboarding-process.png index 1901b2a50..9ba7c91df 100644 Binary files a/docs/operating-model/how-data-space-operations/assets/general-onboarding-process.png and b/docs/operating-model/how-data-space-operations/assets/general-onboarding-process.png differ diff --git a/docs/operating-model/how-data-space-operations/assets/how-data-space-operations.pptx b/docs/operating-model/how-data-space-operations/assets/how-data-space-operations.pptx new file mode 100644 index 000000000..64dd07bae Binary files /dev/null and b/docs/operating-model/how-data-space-operations/assets/how-data-space-operations.pptx differ diff --git a/docs/operating-model/how-data-space-operations/how-data-space-operations.md b/docs/operating-model/how-data-space-operations/how-data-space-operations.md index adbf97f6b..baa40a841 100644 --- a/docs/operating-model/how-data-space-operations/how-data-space-operations.md +++ b/docs/operating-model/how-data-space-operations/how-data-space-operations.md @@ -7,8 +7,7 @@ This chapter outlines the overarching processes and premises to onboard and exch data in the Catena-X data space. This includes the general onboarding process that all participants must complete to join the Catena-X data space. It involves registration and technical integration, as well as compliance with the regulatory framework and verification -through the Gaia-X Digital Clearing House. The introduction of Self Sovereign Identities (SSI) -in Tractus-X Release 23.09 updates the process for offering, exchanging, and using data, +through the Gaia-X Digital Clearing House. The new Self Sovereign Identities (SSI) flow updates the process for offering, exchanging, and using data, while the chapter also covers EDC deployment and usage premises and available support options for participants. @@ -19,52 +18,53 @@ To participate in the data space, all participants must complete the general reg ![General Onboarding Process](./assets/general-onboarding-process.png) *General Onboarding Process* -During **registration**, all participants must fill out their company data, select their data space role, and agree to the regulatory framework via one of the OSPs (see Chapter [Onboarding Service Provider](./../who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md#onboarding-service-provider)). A BPNL (if not yet existing) as well as a Managed Wallet Tenant with BPNL Credential and CX membership Credential are created as part of the registration approval process, which is owned/managed by the operation company. Each participant can collect their identity proofs, certificates and other verifiable information, rights, or services in its identity wallet. +During the onboarding, all participants must fill out their company data, select their data space role, and agree to the regulatory framework via one of the OSPs or the CSP-B (see Chapter [Onboarding Service Provider](./../who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md#onboarding-service-provider)). A BPNL (if not yet existing) as well as an Identity Tenant with BPNL Credential and Catena-X membership Credential are created as part of the registration approval process, which is owned/managed by the operation company. Each participant can collect their identity proofs, certificates and other verifiable information, rights, or services in their identity wallet. -During **technical integration**, the technical user creation and registration of the connectors are essential to enable the company communication with the data space. The technical user enables the customer company to connect the connector with the wallet and the connector registration is needed to ensure that the connector can get found by other data space members. +After the onboarding the user can start with the technical integration, the technical user creation and registration of the connectors are essential to enable the company's communication with the data space. The technical user enables the customer company to connect the connector with the wallet and the connector registration is needed to ensure that the connector of the customer company can be found by other data space members. With that, data space participants can search for all available connectors in Catena-X. -The self-descriptions of newly registered legal entities and connectors are validated by the GXDCH (see Chapter [Gaia-X Compliance](./how-data-space-operations.md#gaia-x-compliance)). This involves signing and issuing credentials to the identity wallet of a DPC, providing proof of Gaia-X compliance and legal entity notarization. Detailed information about the Standard CX-0006 in the [Standard Library](https://catena-x.net/de/standard-library) of the Catena-X Association. +The self-descriptions of newly registered legal entities and connectors are validated by the GXDCH (see Chapter [Gaia-X Compliance](./how-data-space-operations.md#gaia-x-compliance)). This involves signing and issuing credentials to the identity wallet of a DPC, providing proof of Gaia-X compliance and legal entity notarization. Detailed information about the Standard CX-0006 is in the [Standard Library](https://catenax-ev.github.io/docs/standards/overview) of the Catena-X Association. ## Gaia-X Compliance -The Gaia-X Digital Clearing House (GXDCH) is an external service that maximizes trust within the Catena-X data space and interoperability with other data space initiatives based on the Gaia-X Trust Framework. The GXDCH enables the validation of legal entities, ensures Gaia-X compliance, and creates an eIDAS conform digital signature (SelfDescription) for all data space participants. There is one GXDCH provider for the Catena-X data space, which is nominated and managed by the Catena-X Association. To ensure compliance with the Catena-X onboarding process, every OSP must connect to the GXDCH. OSP candidates can request more information during conformity assessment. +The Gaia-X Digital Clearing House (GXDCH) is an external service that maximizes trust within the Catena-X data space, and interoperability with other data space initiatives, based on the Gaia-X Trust Framework. The GXDCH enables the validation of legal entities, ensures Gaia-X compliance, and creates an eIDAS conform digital signature (Self Description) for all data space participants. There is one GXDCH provider for the Catena-X data space, which is nominated and managed by the Catena-X Association. To ensure compliance with the Catena-X onboarding process, the CSP-B must connect to the GXDCH. -## SSI Issuer Concept +## Implementation of the Self Sovereign Identity Concept -The Tractus-X Release 23.09 initiates the introduction of Self Sovereign Identities (SSI), replacing the Dynamic Attribute Provisioning Service (DAPS). The current release and version of SSI allows only one issuer and one centrally managed identity wallet operated by the CSP-B (see Chapter [What: Service Map](./../what-service-map/what-service-map.md)). This also includes the revocation of issued certificates. This is done in cooperation with the Catena-X Association e.g., in case of conscious violation of legal and technical framework. With the 23.09. Release the CSP-B is the single issuer authority of Catena-X credentials. Multi-issuer concept is planned in the following releases. The BPNL can be found on the Catena-X Association website and the portal of the CSP-B. This concept will evolve in future releases, the details of which can be found in Chapter [Further Integration of SSI Technologies](./../outlook/outlook.md#further-integration-of-ssi-technologies). +Self-Sovereign Identity (SSI) is the next step beyond user-centric identity, and that means it begins at the same place: the user must be central to the administration of identity. That requires not just the interoperability of a user’s identity across multiple locations, with the user’s consent, but also true user control of that digital identity, creating user autonomy. In Catena-X there are several different components to implement the SSI approach. This includes the Issuer Component and the BPN DID Resolution Service (BDRS) which is currently classified as Core Service B due to the current state of our technical architecture, and is accordingly also managed by the CSP-B. In addition to the Issuer Component, the CSB-B also operates an Identity Wallet and the Authority Schema Registry. The Authority Schema Registry is managed by the Catena-X Association, which has nominated and commissioned the CSP-B to operate this service. To enable a stable and secure operation, the CSP-B can put the schemas in a dedicated repository. The CSP-B must use the currently operational version in the Catena-X data space. All the components can be seen in the Service Map (see Chapter [What: Service Map](./../what-service-map/what-service-map.md)) This concept will evolve in future releases, the details of which can be found in Chapter [Further Integration of SSI Technologies](./../outlook/outlook.md#further-integration-of-ssi-technologies). ## Data Exchange based on SSI -With the introduction of Self Sovereign Identities (SSI) in the Tractus-X Release 23.09, the processes to participate in a use case as well as offer, exchange, and use data are updated as follows (see Figure [Data Exchange Process](./how-data-space-operations.md#data-exchange-based-on-ssi)): +With the latest Catena-X release the processes to participate in a use case as well as to offer, exchange, and use data are updated as follows (see Figure [Data Exchange Process](./how-data-space-operations.md#data-exchange-based-on-ssi)): ![Data Exchange Process](./assets/data-exchange-process.png) *Data Exchange Process* +> Note: the flow is a comprehensive picture of the actual interactions taking place. It covers the presentation flow. The issuance flow is not visualized. -1. **Participant signs pre-defined use case framework conditions and requests credential via CSP-B** +1. **Initiate Secure Token Creation** - The data consumer must sign and upload the respective use case framework conditions to request the use case participation credential. + Retrieve a One-Time-Token (OTT) to allow the provider to request Verifiable Presentations (VP) within a pre-defined, authorized scope. -2. **Issuer validates request and issues credential** +2. **Query catalog/offers** - The request from the participant (e.g., data consumer) is sent to the issuer (operator) for validation (frame version and existing signature) and confirmation, which triggers the creation of the VC. + With the query of the data provider catalog, the consumer EDC submits the previously generated one-time token to allow the provider to call the VP under #3. -3. **Requests credential** +3. **Query VP** - The customer EDC calls the MIW to retrieve the verified summary credentials, requests the signature and retrieves the verified presentation with the summary credential. + The provider calls the consumer wallet with the provided One-Time-Pad (OTP). The consumer wallet validates the (One-Time-Token) OTT and if successful, submits the VP. -4. **Query catalogue/offers** +4. **Validate VP** - With the query of the data provider catalog, the consumer EDC submits the request with the VP in the request header. Upon successful validation, the issuer generates the verified credential using the MIW component and stores it in the wallet tenant of the customer company wallet. is recreated containing both the previous credentials and the newly added credential. + The provider connector validates the VP and matches the consumer VP scope with the available data offer policy rules configured. 5. **Submit catalog** - The received offer catalog request and the submitted customer VP are validated by the provider EDC. All data offers where the data access policies set by the provider match the verified credentials owned by the data consumer are sent to the customer. Any data offers that require verified credentials that the data consumer does not have will not be sent/published to the data consumer. + Upon successful validation (by the provider EDC), all data offers, where the data access policies set by the provider match the verified credentials owned by the data consumer, are sent to the customer. Any data offers that require verified credentials that the data consumer does not have will not be sent/published to the data consumer. Participation in a Catena-X Use Case requires the selection of at least one standardized purpose. The list of standardized Catena-X purposes can be found in the official [Catena-X Open Digital Rights Language (ODRL) profile](https://github.com/catenax-eV/cx-odrl-profile). 6. **Manual checking of data offering policies** Configured data offer policies must be manually checked by the data consumer. - If a purpose is specified, the purpose must be validated internally by the data consumer. The purpose may refer to an individual contract concluded between the data consumer and the data provider. The data consumer must review the contract and decide whether the policies are acceptable for the specific data offering based on the established policies (see next step 7). - - If no purpose is specified, the negotiation can start immediately, as the access and usage policies are automatically technically enforced and validated by the EDCs. + - If no purpose is specified, the negotiation can start immediately, as the access and usage policies are automatically technically enforced and validated by the connectors. 7. **Decision on the purpose of the data offer** @@ -72,11 +72,11 @@ With the introduction of Self Sovereign Identities (SSI) in the Tractus-X Releas 8. **Contract negotiation** - The data consumer starts the contract negotiation by sending a request for an agreement/contract + The data consumer starts the contract negotiation by sending a request for an agreement/contract. 9. **Contract conclusion/success** - The EDC of the data provider receives the negotiation requests, validates the access and usage policies of the specific data offer requested by the data provider, and matches it with the VP of the data consumer. If the data consumer has all relevant credentials, the agreement is successfully concluded, and an agreement log is stored in both EDCs. + The connector of the data provider receives the negotiation requests, validates the access and usage policies of the specific data offer requested by the data provider, and matches it with the VP of the data consumer. If the data consumer has all relevant credentials, the agreement is successfully concluded, and an agreement log is stored in both connectors. 10. **Data transfer** @@ -95,4 +95,4 @@ Each data space participant has its own organizational structure, consisting of - Data usage takes place instead at the endpoints of the data providers or data consumers, respectively. - Data usage with respect to location and assignment to computer instances/platforms is independent of the runtime environment of the connector itself. -There are various options for organizational structures and data exchange scenarios such as “one legal entity and one site in one country”, “one legal entity and multiple sites in one country” or “one legal entity and multiple sites in different countries”. For more details on possible connector usage scenarios, please refer to our [Initial Onboarding Guide](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/6_Onboarding/CX_-_0006_Registration_and_Initial_Onboarding_v_1.1.1.pdf). This includes also the different options to obtain a connector, e.g., it can be acquired via an ESP, it can be self-developed or adapted from open-source, or it can be part of a business application from a BAP. If the data exchange does not take place between several legal entities within Catena-X as defined above, no EDC is required. An example would be the connection of the OSP to the GXDCH. For this connection no connector is needed, because this is not an exchange of data between two legal entities within Catena-X. +There are various options for organizational structures and data exchange scenarios such as “one legal entity and one site in one country”, “one legal entity and multiple sites in one country” or “one legal entity and multiple sites in different countries”. For more details on possible connector usage scenarios, please refer to our [Initial Onboarding Guide](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/6_Onboarding/CX_-_0006_Registration_and_Initial_Onboarding_v_1.1.1.pdf). This includes also the different options to obtain a connector, e.g., it can be acquired via an ESP, it can be self-developed or adapted from open-source, or it can be part of a business application from a BAP. If the data exchange does not take place between several legal entities within Catena-X as defined above, no EDC is required. An example would be the connection of the CSP-B to the GXDCH. For this connection no connector is needed, because this is not an exchange of data between two legal entities within Catena-X. diff --git a/docs/operating-model/how-life-cycle-management/assets/MajorVersionCX.png b/docs/operating-model/how-life-cycle-management/assets/MajorVersionCX.png new file mode 100644 index 000000000..1fbb5f698 Binary files /dev/null and b/docs/operating-model/how-life-cycle-management/assets/MajorVersionCX.png differ diff --git a/docs/operating-model/how-life-cycle-management/assets/how-life-cycle-management.pptx b/docs/operating-model/how-life-cycle-management/assets/how-life-cycle-management.pptx new file mode 100644 index 000000000..00b4cb23b Binary files /dev/null and b/docs/operating-model/how-life-cycle-management/assets/how-life-cycle-management.pptx differ diff --git a/docs/operating-model/how-life-cycle-management/assets/impact-on-the-network.png b/docs/operating-model/how-life-cycle-management/assets/impact-on-the-network.png new file mode 100644 index 000000000..05bc7c365 Binary files /dev/null and b/docs/operating-model/how-life-cycle-management/assets/impact-on-the-network.png differ diff --git a/docs/operating-model/how-life-cycle-management/assets/release-schedule.png b/docs/operating-model/how-life-cycle-management/assets/release-schedule.png new file mode 100644 index 000000000..5cf3921ba Binary files /dev/null and b/docs/operating-model/how-life-cycle-management/assets/release-schedule.png differ diff --git a/docs/operating-model/how-life-cycle-management/how-life-cycle-management.md b/docs/operating-model/how-life-cycle-management/how-life-cycle-management.md index 3a62cfa3b..06914220d 100644 --- a/docs/operating-model/how-life-cycle-management/how-life-cycle-management.md +++ b/docs/operating-model/how-life-cycle-management/how-life-cycle-management.md @@ -3,13 +3,102 @@ sidebar_position: 1 --- # How: Life Cycle Management -Managing versions and changes of different artifacts in federated data spaces is critical to ensure compatibility, interoperability, and security. The life cycle management of the Catena-X ecosystem is coordinated by the Catena-X Association and includes the releases in the Catena-X Association and in the Eclipse Tractus-X Project (see Figure [Overview Life Cycle Management](./how-life-cycle-management.md)). It is planned to provide quarterly releases including **one major** and **three minor** releases per year. Both releases follow calendar versioning (see [CalVer](https://calver.org/)), whereas their artifacts such as standards, normative documents, products, and KITs follow semantic versioning (see [SemVer](https://semver.org/)). To ensure backward compatibility in the future (see Chapter [Backward Compatibility](./../outlook/outlook.md#backward-compatibility)), versioning and passing of predefined test cases of each individual artifact is mandatory. +Managing versions and changes of different artifacts in federated data spaces is critical to ensure compatibility, interoperability, and security. The life cycle management of the Catena-X ecosystem is coordinated by the Catena-X Association and includes the releases in the Catena-X Association and in the Eclipse Tractus-X Project (see Figure [Overview Life Cycle Management](./how-life-cycle-management.md)). + +Catena-X will provide **one major** and **one minor** ecosystem release per year. This means that each release of Catena-X can contain e.g. standards, normative documents of two quarterly releases of Tractus-X. + +Tractus-X will provide quarterly releases including **one major** and **three minor** releases per year. The releases follow calendar versioning (see [CalVer](https://calver.org/)), whereas their artifacts such as feature, reference implementations, and KITs follow semantic versioning (see [SemVer](https://semver.org/)). To ensure backward compatibility in the future, versioning and passing of predefined test cases of each individual artifact is mandatory. Exceptions, e.g. regulatory requirements, have to be approved by the Catena-X Association. ![Overview Life Cycle Management](./assets/overview-life-cycle-management.png) *Overview Life Cycle Management* The Catena-X Association release includes all binding and certification-relevant artifacts such as standards (e.g., API-specifications, semantic models) and normative documents for all data space participants. The Tractus-X release contains all open-source products (including services or helm charts) of the cxOS and business applications as well as KITs. In addition, there are various commercial or self-developed solutions for business applications and services following individual release cycles and versioning schemes. -Both the Tractus-X release and any commercial or self developed solutions must adhere to Catena-X standards and other relevant normative documents. +Both the Tractus-X release and any commercial or self-developed solutions must adhere to Catena-X standards and other relevant normative documents to get deployed. + +Open-source products are required to fulfill the [Tractus-X release guideline(TRGs)](https://eclipse-tractusx.github.io/docs/release/) and take part in the integration tests to be part of a quarterly Tractus-X release. For critical issues (e.g., security issues), hot fixes may be released to fix a bug in the active Catena-X operating system that interrupts the normal release cycle. + +## Definition of breaking changes and the impact + +Catena-X defines the type of changes and thus also those of breaking changes according to semantic versioning (see [SemVer](https://semver.org/)). There are therefore major, minor and patch changes. As shown in the figure above, there are major changes at a maximum once a year. Minor changes or patches can be introduced independently of this. These can be independent improvements or changes. However, every change must be compatible with the applicable standards. + +### Impact of changes on the Catena-X network + +In addition to the differentiation of changes into major, minor and patch described above, there are three different categories of major (breaking) changes. The examples mentioned can fall into this category. Depending on the changes, the component in the example may also fall into a different category: + +**Intra-Company** +These are changes that only have effects and dependencies within a company. This means that there are no dependencies on third parties and the upgrade can be planned exclusively internally. An example of such a component is SD-Factory, BPN-Issuer. + +**Inter-Company** +These are changes that only have an effect on certain partners. An upgrade must therefore be agreed between the partner(s). The number of partners is limited and a joint approach must then be agreed upon. An example of such a component is the: GXDCH for the CSP-B. + +**Network** +These changes have an impact on all participants of the Catena-X network. The objective is to abstract these as coordination between all participants is not possible. One possibility of abstraction is that one component supports several versions. An example of such a component is: EDC + +![Differences from major (breaking) changes](./assets/impact-on-the-network.png) +*Differences from major (breaking) changes* + +## Release Management + +There are two main channels in the Catena-X ecosystem that develop artifacts - Catena-X Association and Tractus-X. The Catena-X Association coordinates the releases for both and ensures compatibility. Moreover, through dedicated release management, the Catena-X Association also carefully evaluates any modifications to the productive network and provides all network participants time to adapt to any changes performed. + +As can be seen in the figure, in addition to the Tractus-X level, which releases quarterly features, reference implementations and KITs, there is the Catena-X Association, which publishes various governance documents such as the semantic models or the standards, as well as the ecosystem. This reflects all participants of the productive Catena-X network. + +![Release schedule Catena-X](./assets/release-schedule.png) +*Release schedule* + +A major release may contain critical breaking changes that have a major impact on data space participants, such as changes to enablement services. A minor release contains backward compatible functionality. In addition, patch versions provide backward compatible bug and security fixes. The Tractus-X project has an overarching qualification process that all official quarterly Tractus-X releases adhere to. This process applies E2E activities for testing and security (relevant release candidates in compound) that stakeholders can build on. Each component can be released on demand on a higher cadence. + +The Catena-X data space aims to support a parallel +phase of two major versions (each valid for a minimum of 12 months): + +1. Current +2. Maintenance + +There is a dedicated date, when the current version of Catena-X and Tractus-X gets in maintenance mode. After that, the maintenance version will be available for at least 12 months to ensure a smooth upgrade process for all participants of the Catena-X data space. This means that both major version are supported, i.e. get required security fixes and bug fixes without migration to the next higher major version. A deployed major version is supported for a minimum of two years. + +All participants doing changes that are network-breaking or inter-company have to ensure one of the following variants to allow a smooth upgrade process: + +1. Running two major versions with the same technical component +2. Running a technical component for each major version, with data migration in between to have the data available in both components + +If the change only affects the component itself (run by one company, i.e. intra-company change), then the company only needs to run one version. It is handled within the company. + +This approach enables each participant to organize the upgrade on its own, because the surrounding technical component supports the current and maintenance valid version. + +### Schedule + +As can be seen in the illustration (see Figure [Major Version Release](./how-life-cycle-management.md#release-management)), there is Tractus-X at the lowest level, which has a release cycle of 3 months and therefore generates 4 releases per year. At the middle level is the Catena-X association which defines the scope for each major and minor release (only the scope of the major release is shown in the figure). This scope is defined together with the various other technical committees and expert groups. This scope then contains the various artifacts of the association, as well as a reference to the corresponding Tractus-X version of the reference implementations. + +Major changes are always introduced by the Catena-X Association scope and are part of the releases presented. The minor release, which always takes place at the earliest 6 months after the major release, contains minor changes to the Catena-X Association artifacts. Other minor changes from other parties are possible at any time, as they are by definition compatible with the previous version. Patches can be introduced by any party at any time, as they must also be compatible with the previous version. + +#### Phases + +The development process in Catena-X is based on three phases: + +1. Planning phase: Tractus-X and Catena-X are planning together. +2. Development phase: During this phase Catena-X and Tractus-X will develop reference implementations and standards covering the developed software. +3. Deployment phase: After development, the components will be deployed to the productive network. + +Following the quarterly development cycle of Tractus-X, the development takes one quarter and succeeds the planning phase. The deployment phase to the network will also take maximum one quarter, but happens at most two times a year, including one minor and one major release of an official ecosystem release. + +#### Release Governance + +The Release Governance is carried out by the Catena-X Association and ensures compatibility, stability and overall reliability of the ecosystem by following a set amount of principles, e.g. architecture guidelines. For this purpose, the Catena-X Association installs a committee, comprised of representatives from relevant stakeholder groups. + +The following milestones are instrumental and constitute the official funnel for deploying ecosystem releases: + +1. **Planning Gate** *after* planning phase: The planning gate criteria are defined by the Catena-X Association, e.g. architecture guidelines, standards, etc. Additionally, the impact of the changes has to be assessed and all network breaking changes require an explicit decision to be included in an official Catena-X development cycle. Moreover, *during* development phase, the Catena-X Association resolves to solve issues regarding compatibility and release management, i.e. communication between components. +2. **Deployment Gate** *after* development phase: After the development phase has concluded, the Catena-X Association formally approves an ecosystem release comprised of a set of coherent standards, normative documents and guidance regarding complementary Tractus-X products and reference implementations. The deployment gate initiates the deployment phase. + +### Introduction of the release schedule + +As can be seen below the ecosystem release at the end of 2024 is the start of release management and naming. The release at the end of 2024 is therefore a hard network change resulting in an upgrade day. This is the last scheduled Catena-X release with this category of impact. Starting with the development of Tractus-X 24.12, the implementation will be carried out with the aim of making the release compatible with [Jupiter]. The same applies to the further creation of the Catena-X Association's artifacts. In this first phase there is only one major release. The complete implementation of 2 major releases running in parallel will be available after the next major ecosystem release [Jupiter]. + +The details of the technical implementation and the process for defining the releases can be found in chapter [Backwards compatibility](./how-life-cycle-management.md#backwards-compatibility). + +## Backwards compatibility + +Compatibility between the releases is one of the cornerstones of a stable network. There are major versions with potential breaking changes, but such changes have to work with the grace period of the maintenance version in mind. This means that the evolution is ensured by following the approach of two versions available at the same time. -Open-source products are required to fulfill the [Tractus-X release guideline(TRGs)](https://eclipse-tractusx.github.io/docs/release/) and take part in our integration tests to be part of a quarterly Tractus-X release. For critical issues (e. g., security issues), hot fixes may be released to fix a bug in the active Catena-X operating system that interrupts the normal release cycle. +As described in [Release governance](./how-life-cycle-management.md#release-governance), there are not only architecture guidelines to define the compatibility, but there is a governance body to check the fulfillment of the guidelines of each version. diff --git a/docs/operating-model/legal/_category_.json b/docs/operating-model/legal/_category_.json new file mode 100644 index 000000000..9e9d6f935 --- /dev/null +++ b/docs/operating-model/legal/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Legal", + "position": 12, + "collapsible": true, + "collapsed": true +} \ No newline at end of file diff --git a/docs/working-model/00-legal/legal.md b/docs/operating-model/legal/legal.md similarity index 100% rename from docs/working-model/00-legal/legal.md rename to docs/operating-model/legal/legal.md diff --git a/docs/operating-model/operating-model/_category_.json b/docs/operating-model/operating-model/_category_.json deleted file mode 100644 index 9fe5db050..000000000 --- a/docs/operating-model/operating-model/_category_.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "label": "Operating Model", - "position": 1, - "collapsible": true, - "collapsed": true -} \ No newline at end of file diff --git a/docs/operating-model/operating-model/assets/operating-model.png b/docs/operating-model/operating-model/assets/operating-model.png deleted file mode 100644 index ce64e811f..000000000 Binary files a/docs/operating-model/operating-model/assets/operating-model.png and /dev/null differ diff --git a/docs/operating-model/operating-model/operating-model.md b/docs/operating-model/operating-model/operating-model.md deleted file mode 100644 index 44b5ec7ef..000000000 --- a/docs/operating-model/operating-model/operating-model.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_position: 1 ---- -# Catena-X Operating Model - -:::danger -This page is currently an MVP and is under construction. The content shown here is also labelled exclusively as DRAFT and is for illustrative purposes only and may not be used in any way in productive operation. -::: - -![Operating Model](./assets/operating-model.png) -*Operating Model* diff --git a/docs/operating-model/outlook/assets/outlook-for-further-decentralization.png b/docs/operating-model/outlook/assets/outlook-for-further-decentralization.png new file mode 100644 index 000000000..3e5bbe2aa Binary files /dev/null and b/docs/operating-model/outlook/assets/outlook-for-further-decentralization.png differ diff --git a/docs/operating-model/outlook/assets/outlook.pptx b/docs/operating-model/outlook/assets/outlook.pptx new file mode 100644 index 000000000..9c427ae57 Binary files /dev/null and b/docs/operating-model/outlook/assets/outlook.pptx differ diff --git a/docs/operating-model/outlook/assets/timeline-for-further-decentralization.png b/docs/operating-model/outlook/assets/timeline-for-further-decentralization.png deleted file mode 100644 index 3023b368e..000000000 Binary files a/docs/operating-model/outlook/assets/timeline-for-further-decentralization.png and /dev/null differ diff --git a/docs/operating-model/outlook/outlook.md b/docs/operating-model/outlook/outlook.md index 5a3ea3c3b..1d2af5a15 100644 --- a/docs/operating-model/outlook/outlook.md +++ b/docs/operating-model/outlook/outlook.md @@ -5,32 +5,16 @@ sidebar_position: 1 The Catena-X Operating Model is a normative document within the regulatory framework, which is binding for all participants in the Catena-X data space. It describes the status of our data space artifacts, including roles, services, and processes along with their respective roadmaps. As Catena-X is an ongoing journey, all of these artifacts will continuously evolve to promote broader adoption and scalability, ensuring maximum interoperability, and (data) sovereignty. -## Industry Core - -The Industry Core aims to reduce the complexity of multi-tier connections within the decentralized Catena-X data space and to act as an enabler for data-driven use cases like tracking a product carbon footprint (PCF) value or circular economy. Reusing common components and standards (especially data provisioning of digital twins of parts) across different use cases promotes efficiency and interoperability. To enable onboarding for corporations that have different legal entities, concepts for a corporate BPNL are also created. This enables a simple participation via a company-group-wide BPNL. The industry core fosters the realization of seamless data chains, with one use case benefiting from another. As a result, cross-domain network effects and n-tier use cases become possible. - ## Increase Decentralization of Core Services -Catena-X follows a business-oriented decentralization approach that aims to achieve interoperability and data sovereignty while balancing manageability of complexity, and technical maturity. Therefore, Core Services B will gradually transition into onboarding services or Core Services A, if appropriate. Please find below the timeline for the upcoming decentralization of Core Services B (see Figure [Timeline for further Decentralization](./outlook.md#increase-decentralization-of-core-services)). - -![Timeline for further Decentralization](./assets/timeline-for-further-decentralization.png) -*Timeline for further Decentralization* - -### Release v23.09 - -Due to organizational and technical limitations, the services associated with the CSP-A and OSP roles can only be operated once and must therefore temporarily be offered by the nominated CSP-B. - -### Release v23.12 (planned) - -With the introduction of new identity synchronization functions, multiple CSP-A and OSP can operate the corresponding services and collaborate. In addition, there will be new CSP-B services such as the Policy and Credential Hub. - -### Releases 2024 (planned) +Catena-X follows a business-oriented decentralization approach that aims to achieve interoperability and data sovereignty while balancing manageability of complexity, and technical maturity. Therefore, Core Services B will gradually transition into onboarding services, Core Services A or Enablement Services, if appropriate. In the figure, the various services that are currently planned to be decentralized in the long term are marked in green. Please find below the outlook for the upcoming decentralization of Core Services B (see Figure [Outlook for further Decentralization](./outlook.md#increase-decentralization-of-core-services)). -With an increasing decentralization of services, Core Services B are shifted step by step to Core Services A and the decentralized portfolio of Onboarding Service Provider likewise increases. For future releases, committees, expert, and working groups will be coordinated to develop a detailed decentralization roadmap under the supervision of the Catena-X Association. +![image](./assets/outlook-for-further-decentralization.png) +*Outlook for further Decentralization* ## Further Integration of SSI Technologies -To realize the Catena-X vision of a decentralized data space, we will further develop our SSI technologies. Future releases will enable the use of both managed identity wallets and self-provisioned identity wallets. To enable the technical enforcement of policies, it is planned to introduce a policy hub and policy code templates to also provide the information transparently to the participants. This also includes the decentralization of the issuer service and logging functionality for agreements. To further strengthen trust in the data space, we will introduce the option to define various root trust anchors (e.g., the Catena-X Association). This will also allow the identity wallet to be decentralized and allow multiple issuers. In addition, a chain of trust will be established to prove that a given credential comes from a trusted source according to the Catena-X Governance Framework. The concept is still under development and will be released in one of the next versions (by May 2024). While developing this concept, the concepts of the Policy Hub and the Certifications Hub will also be concretized. An illustration of this can be found in Chapter [Data Exchange based on SSI - Next Steps](./../appendix/appendix.md#data-exchange-based-on-ssi---next-steps). +To realize the Catena-X vision of a decentralized data space, we will further develop our SSI technologies. Future releases will enable the use of both managed identity wallets and self-provisioned identity wallets. Furthermore, it is planned to enable multiple issuers, e.g. through the decentralization of the issuer component by changing its classification from Core Service B, to a "sub-role" of the CSP-A including the introduction of a new role "Issuer Authority" to operate the component. To further strengthen trust in the data space, we will introduce the option to define various root trust anchors (e.g., the Catena-X Association). In addition, a chain of trust will be established to prove that a given credential comes from a trusted source according to the Catena-X Governance Framework. Those concepts are currently still under development. ## Data Space Interoperability @@ -46,8 +30,8 @@ To achieve this in areas such as APIs, semantic models, and procedural specifica - **Developing technical specifications** and **reference implementations** in Eclipse Tractus-X that follow the required standards to lay the technical foundation. - **Coordinating** closely with different **operators** to execute rollout and implementation of the different versions and releases. -## Sanctions +## Enforcement of compliance with normative documents -Following its GoLive, the Catena-X data space will grow in participants and complexity. Consequently, ensuring compliance of all participants with established rules, regulations, and standards becomes increasingly relevant. +The Catena-X data space will grow in participants and complexity. Consequently, ensuring compliance of all participants with established rules, regulations, and standards becomes increasingly relevant. -Moving forward, concepts of imposing restrictions or penalties on individuals, organizations, or entities that engage in actions or behaviors that are deemed harmful, illegal, or unethical within the context of data management, privacy, and security will be evaluated and developed. These sanctions will aim to deter, correct, or punish noncompliant behavior, thereby safeguarding data integrity, protecting individual rights, and maintaining the trust and credibility of the data ecosystem. +As outlined in the main chapter, we are currently laying the foundational elements to be utilized later in the various processes still being developed for productive operations. This development of multiple processes is iterative and will be published in a forthcoming operating model. In addition to the general process that needs to be developed, the association is also investigating the possibility of imposing other consequences such as fines in the event of non-compliance. diff --git a/docs/operating-model/what-service-map/assets/service-map-deployment-view.png b/docs/operating-model/what-service-map/assets/service-map-deployment-view.png deleted file mode 100644 index 099f5b63a..000000000 Binary files a/docs/operating-model/what-service-map/assets/service-map-deployment-view.png and /dev/null differ diff --git a/docs/operating-model/what-service-map/assets/service-map.png b/docs/operating-model/what-service-map/assets/service-map.png new file mode 100644 index 000000000..041d94eba Binary files /dev/null and b/docs/operating-model/what-service-map/assets/service-map.png differ diff --git a/docs/operating-model/what-service-map/assets/what-service-map.pptx b/docs/operating-model/what-service-map/assets/what-service-map.pptx new file mode 100644 index 000000000..01c9800b7 Binary files /dev/null and b/docs/operating-model/what-service-map/assets/what-service-map.pptx differ diff --git a/docs/operating-model/what-service-map/what-service-map.md b/docs/operating-model/what-service-map/what-service-map.md index 21b39b6fd..3366283a5 100644 --- a/docs/operating-model/what-service-map/what-service-map.md +++ b/docs/operating-model/what-service-map/what-service-map.md @@ -4,23 +4,23 @@ sidebar_position: 1 # What: Service Map The architecture of the Catena-X Operating System (cxOS) is derived from the reference -architectures of Industrial Data Space Association (IDSA) and Gaia-X. The cxOS consists of -three areas: Core, Onboarding, and Enablement Services shown in Figure [Service Map](./what-service-map.md). -![Service Map (Deployment View)](./assets/service-map-deployment-view.png) +architectures of the International Data Spaces Association (IDSA) and Gaia-X. The cxOS consists of three areas: Core, Onboarding, and Enablement Services shown in Figure [Service Map](./what-service-map.md). + +![Service Map (Deployment View)](./assets/service-map.png) *Service Map (Deployment View)* -The cxOS is the technical foundation enabling business use cases to operate in a network-enabled manner across company boundaries. The operating system offers various capabilities: +The operating system (cxOS) is the technical foundation, enabling business use cases to operate in a network-enabled manner across company boundaries. The cxOS offers various capabilities: ## Enablement Services -The Enablement Services are a bundle of decentral services that enable participation in the Catena-X data space. Each participant must deploy and use the enablement services to connect to the data space and enable standardized interactions based on the requirements of the respective use case. They ensure the strategic value proposition of technical/semantic interoperability and (data) sovereignty. +The Enablement Services are a bundle of decentral services that enable participation in the Catena-X data space. Each participant must deploy and use the enablement services to connect to the data space and enable standardized interactions, based on the requirements of the respective use case. They ensure the strategic value proposition of technical/semantic interoperability and (data) sovereignty. -The connector (e.g., EDC) based on the data space protocol and the identity wallet form the mandatory basis of enablement services enabling standardized technical connectivity and sovereign data exchange. All participants can use them to establish a basic connection to the data space, independent of the business use case. +The connector (e.g., EDC), based on the Data Space Protocol, and the identity wallet, form the mandatory basis of enablement services enabling standardized technical connectivity and sovereign data exchange. All participants can use them to establish a basic connection to the data space, independent of the business use case. -In addition to generic data-exchange capabilities, enabling services include context-specific service offerings. Examples are the Asset Administration Shell (AAS) as harmonized access layer for digital twins, the Decentral Digital Twin Registry (DDTR) for local discoverability of digital twins in decentral organized data spaces or the Item Relationship Service (IRS) for building data chains and iterating through a tree structure of digital twins. +In addition to generic data exchange capabilities, enabling services include context-specific service offerings. Examples are the Asset Administration Shell (AAS) as a harmonized access layer for digital twins, the Decentral Digital Twin Registry (DDTR) for local discoverability of digital twins in decentral organized data spaces or the Item Relationship Service (IRS) for building data chains and iterating through a tree structure of digital twins. -Please note that there are various options for running enablement services, ranging from leveraging software-asa-service solutions to local deployments of open-source reference implementations. Further information on deployment and usage premises can be found in Chapter [EDC Deployment and Usage Premises](./../how-data-space-operations/how-data-space-operations.md#edc-deployment-and-usage-premises). +Please note that there are various options for running enablement services, ranging from leveraging software-as-a-service solutions to local deployments of open-source reference implementations. Further information on deployment and usage premises can be found in Chapter [EDC Deployment and Usage Premises](./../how-data-space-operations/how-data-space-operations.md#edc-deployment-and-usage-premises). ## Core Services @@ -30,21 +30,27 @@ In contrast to Enablement Services, Core Services are provided and operated by C **Core Services B** lists Core Services that can only be operated once in the Catena-X data space due to business reasons or technical limitations and are therefore tendered via the nomination process of the Association. -Some of the Core Services, such as the Managed Identity Wallet, are by nature Enablement Services, but because of technical reasons they are considered Core Services B as an interim solution. - ## Onboarding Services -The Onboarding Services are provided and operated by OSPs. Onboarding Services enable participants to onboard into the Catena-X data space. As shown in Chapter [Increase Decentralization of Core Services](./../outlook/outlook.md#increase-decentralization-of-core-services), the scope of Onboarding Services will change over time. The Onboarding Services can be divided into two areas: +The Onboarding Services are provided and operated by OSPs. Onboarding Services enable participants to onboard into the Catena-X data space. The Onboarding Services can be divided into two areas: **Onboarding Services** list the services that ensure a standardized and compliant Catena-X onboarding process (e.g., registration process). -**External Onboarding Services** list the services that OSPs must integrate and use to implement a trusted onboarding process but are developed and operated by an external initiative or provider. +**Trust Partners** list the services that CSP-B must integrate and use to implement a trusted onboarding process but are developed and operated by an external initiative or provider. ## Use Cases -The goal of a Catena-X use case is to solve a specific business problem and to create value for data providers and consumers. To do this, the Catena-X Association demands and promotes that use cases create Standards and KITs to enable a multi-vendor ecosystem of interoperable and compatible business applications (see: business application). Achieving network effects in the Catena-X ecosystem is critical to success and depends on the active participation of users and the creation of appealing business apps, especially for SMEs +The goal of a Catena-X use case is to solve a specific business problem and to create value for data providers and consumers. To do this, the Catena-X Association demands and promotes that use cases create Standards and KITs to enable a multi-vendor ecosystem of interoperable and compatible business applications. Achieving network effects in the Catena-X ecosystem is critical to success and depends on the active participation of users and the creation of appealing business apps, especially for SMEs. + +## Business Partner Data Management vs. Golden Record vs. Value Added Services (Business Apps) + +**Business Partner Data Management** refers to the whole Catena-X use case. This use case addresses high data retention costs by creating a "Golden Record" with a unique Business Partner Number (BPN) to harmonize, improve, and manage business partner data efficiently, reducing maintenance and validation expenses and supporting decentralized identity management on a company-level + +**Golden Record Process (cleansing)** describes the cleansing of the data in the Golden Record. This ensures that the data is unique and correct. This creates a high-quality record in the network by identifying business partners through Legal Entity, Legal Address, and Site, ensuring data accuracy and consistency + +**Value Added Services (VAS)** always require access to the data generated by the Golden Record process, which is part of the BPDM use case. This means VAS always relies on BPDM data. These services therefore require a deep integration into BPDM - thus the pure use of the BPN-L, BPN-S, and BPN-A is excluded to qualify for a VAS, e.g. the use case Traceability utilizes the BPNL but is not a VAS. -### KITs – Keep It Together +## KITs – Keep It Together KIT, short for Keep It Together, bundles all necessary resources and technical documentation designed to adopt a Catena-X use case for all data space participants (see Figure [KITs Toolbox](./what-service-map.md#kits--keep-it-together)). @@ -57,16 +63,58 @@ DPCs that are part of the automotive value chain and strive to participate in a BAPs interested in offering a business application for a specific use case on one of the Catena-X marketplaces. These companies need to align their existing solutions with Catena-X requirements. Within a KIT, they receive guidelines and the technical support necessary for adapting their solutions to meet Catena-X conformity based on our five steps to Catena-X: Inform, connect, boost, adapt, utilize. KITs are the way forward to create a valuable multi-vendor ecosystem to promote seamless interoperability between different commercial solutions. -### New Use Cases and Direct Collaboration +### Industry Core + +The Industry Core is an integrative layer between the industry-agnostic dataspace foundation and the use cases supported by the KITs of Catena-X (see [Industry Core KIT](https://eclipse-tractusx.github.io/docs-kits/category/industry-core-kit)). It facilitates the seamless integration of multiple use cases and related applications by leveraging common components and standards, particularly in terms of data provisioning for digital twins. + +Specifically, the industry core ensures that applications within the automotive industry can access shared functionalities, including shared semantic models, Asset Administration Shell (AAS) and Digital Twin Registry (DTR) configurations for linking digital twins of components and vehicles, as well as guidelines for setting up required network services (e.g. EDC). Other use cases (e.g., product passport) can use the digital twins in business applications with use case specific business logic and extended semantic models. + +The industry-agnostic dataspace foundation includes general dataspace services (e.g., EDC, Identity Wallet, Digital Twin Registry), some of which are defined and developed by other dataspace initiatives (e.g., Gaia-X, IDSA, Eclipse Dataspace Working Group). + +Benefits of the industry core include the: + +- re-usability of semantic models of digital twins via defining archetypes of serialized parts manufacturing +- seamless integration of multiple use cases and related applications by leveraging common components and standards, particularly in terms of data provisioning for digital twins +- efficiency and interoperability across different use cases + +### Knowledge Agent + +The Knowledge Agent facilitates efficient and secure data exchange using the SPARQL protocol and the EDC. It standardizes data from various sources into unified formats and manages complex dependencies to ensure seamless communication and data retrieval. Semantic knowledge graphs enhance the understanding and accessibility of complex data structures. + +## New Use Cases and Direct Collaboration + +In addition to the first 10 use cases that were initially developed in the Catena-X Consortium and are now governed by the Association Committees (e.g., Sustainability Committee), data space participants have the following scenarios for collaboration: + +### Initiate a new use case + +Any Catena-X Association member can initiate a new use case by creating a working group in the Catena-X Association or expanding an existing committee (whatever suits the purpose best, the final judgment is made by the Board of the Association). The goal of a committee or working group is to discuss and define a common vision, roadmap, standards, KITs, and other open-source artifacts for the use cases with a focus on interoperability and data sovereignty to create multi-tier value chains for a dedicated business process. + +To validate the value proposition or technical specifications, a new use case can be tested in the future either in a sandbox environment of the CSP-B or in the test environments of the Catena-X Association. Note that new use cases without standards provide only limited interoperability, require individual use case policies, and cannot be certified and thus not be listed on one of the marketplaces and are therefore not supported and trusted. + +### Direct collaboration (no multi-tier approach) + +The Catena-X data space also enables secure and sovereign data exchange for direct collaboration between DPCs. In this scenario, the DPCs are responsible for defining a bilateral semantic model, as well as appropriate usage and access policies. Alternatively, they can make use of existing usage and access policies that meets their needs. The goal of the Catena-X data space remains to always create interoperable use cases with consistent data chains. Note that direct collaboration without standards provides only limited interoperability and cannot be certified and thus not be listed on one of the marketplaces. + +### Sandboxes (BETA) + +**Catena-X Sandboxes** contain all cxOS services required for the operation of a minimum valuable Catena-X data space, namely: + +- CSP-B services (excluding the cleansing service of BPDM and GXDCH integration) +- OSP services + +Catena-X Sandboxes offer participants the option to try out the network and its features while still using test data. On the one hand, they serve the purpose of offering a **Proof of Concept (POC) environment**, both for future Catena-X releases as well as for interested parties to “try out” Catena-X before migrating to the productive operating environment. On the other hand, they provide the foundation for more automated **Catena-X conformity assessment**. Catena-X Sandboxes will require certification in the future and are distinctly recognizable by an official Catena-X label. -In addition to the first 10 use cases that have been initially developed in the Catena-X Consortium and are now governed by the Association Committees (e.g., Sustainability Committee), data space participants have the following scenarios for collaboration: +Sandboxes must visibly distinguish their services from the productive Catena-X operating environment provided by the official CSP-B (e.g. through a disclaimer to its users) in combination with advertising a clear path into the productive Catena-X operating environment for any user that intends to join the Catena-X data space. -#### Initiate new use case +Given that the brand of Catena-X draws much of its value from trust, any Catena-X Sandbox user is required to formally onboard onto Catena-X via an OSP and accept the general terms and conditions of the Catena-X data space (10 golden rules, data exchange governance...) before onboarding onto a Catena-X Sandbox. -Any Catena-X Association member can initiate a new use case by creating a working in the Catena-X Association or expand an existing committee (whatever suits the purpose best, the final judgement is made by the Board of the Association). The goal of a committee or working group is to discuss and define a common vision, roadmap, standards, KITs, and other open-source artefacts for the use cases with focus on interoperability and data sovereignty to create multi-tier value chains for a dedicated business process. +The following conditions apply to any Catena-X Sandbox: -To validate the value proposition or technical specifications, a new use case can be tested in future either in a sandbox environment of the CSP-B or in the test environments of the Catena-X Association. Note that new uses cases without standards provide only limited interoperability, require individual use case policies, and cannot be certified and thus not be listed on one of the marketplaces and are therefore not supported and trusted. +- Catena-X Release: any officially supported Catena-X Release +- Data: limited to test data +- Apps & Solutions offered: Catena-X certified, if standardized Catena-X services are offered; Non-certified if no Catena-X standards exist (see *Direct collaboration (no multi-tier approach*)). +- Users: registered Catena-X data space participants only -#### Direct collaboration (no multi-tier approach) +#### Limitations -The Catena-X data space also enables secure and sovereign data exchange for direct collaboration between data provider and consumer. In this scenario, the data provider and consumer are responsible for defining a bilateral semantic model, as well as appropriate usage and access policies. Alternatively, they can make use of existing usage and access policy that meets their needs. The goal of the Catena-X data space remains to always create interoperable use cases with consistent data chains. Note that direct collaboration without standards provides only limited interoperability and cannot be certified and thus not be listed on one of the marketplaces. +Catena-X aims to foster new forms of innovation and scaling. Sandboxes promise to offer much in order to enhance our network in that regard. Thereby, we are providing the limited option (BETA) to host and participate in Catena-X Sandboxes according to the criteria listed in Chapter [Who - Roles in the Ecosystem](./../who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md). This option is currently limited until October 2024 in order to further evaluate the criteria and market feedback for our ecosystem. All feedback collected will flow into future versions of the Catena-X Operating Model. diff --git a/docs/operating-model/who-roles-in-the-catena-x-ecosystem/assets/role-overview-and-relationships.png b/docs/operating-model/who-roles-in-the-catena-x-ecosystem/assets/role-overview-and-relationships.png index 3afb02209..3993f59dd 100644 Binary files a/docs/operating-model/who-roles-in-the-catena-x-ecosystem/assets/role-overview-and-relationships.png and b/docs/operating-model/who-roles-in-the-catena-x-ecosystem/assets/role-overview-and-relationships.png differ diff --git a/docs/operating-model/who-roles-in-the-catena-x-ecosystem/assets/who-roles-in-the-catena-x-ecosystem.pptx b/docs/operating-model/who-roles-in-the-catena-x-ecosystem/assets/who-roles-in-the-catena-x-ecosystem.pptx new file mode 100644 index 000000000..8377c15c5 Binary files /dev/null and b/docs/operating-model/who-roles-in-the-catena-x-ecosystem/assets/who-roles-in-the-catena-x-ecosystem.pptx differ diff --git a/docs/operating-model/who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md b/docs/operating-model/who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md index dd4c2a1f2..c2df6c181 100644 --- a/docs/operating-model/who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md +++ b/docs/operating-model/who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md @@ -3,26 +3,26 @@ sidebar_position: 1 --- # Who: Roles in the Catena-X ecosystem -The Catena-X ecosystem operates on the principle of multiple distinct roles, designed to create an appealing and functional data space (see [Figure Role Overview and Relationships](./who-roles-in-the-catena-x-ecosystem.md#overview-of-roles)). Participants can take on one or more roles in any combination, and multiple participants can fulfill the same role except for the CSP-B role. The CSP-B role can only exist once in the data space due to complexity and technical reasons. Provider roles receive a label through a certification or qualification process to demonstrate that they are trusted partners (see Chapter [How: Life Cycle Management](./../how-life-cycle-management/how-life-cycle-management.md)). +The Catena-X ecosystem operates on the principle of multiple distinct roles, designed to create an appealing and functional data space (see Figure [Role Overview and Relationships](./who-roles-in-the-catena-x-ecosystem.md#overview-of-roles)). Participants can take on one or more roles in any combination, and multiple participants can fulfill the same role except for the CSP-B role. The CSP-B role can only exist once in the data space due to complexity and technical reasons. Provider roles receive a label through a certification or qualification process to demonstrate that they are trusted partners (see Chapter [How: Life Cycle Management](./../how-life-cycle-management/how-life-cycle-management.md)). ## Overview of roles -![Role Overview and Relationships](./assets/role-overview-and-relationships.png) +![Role Overview and Relationships](./assets/role-overview-and-relationships.png) *Role Overview and Relationships* ## Detailed description of each role -Below, each role that a participant can assume in the Catena-X data spaces is described in detail, along with its assigned description, responsibilities, relationships, prerequisites, and complements. Please refer to Chapter [Role Relationships](./../appendix/appendix.md#role-relationships). for a comprehensive overview of the relationships between these roles as well as a definition of the relationship type and Chapter [What: Service Map](./../what-service-map/what-service-map.md) for an overview of the Service Map. +Below, each role that a participant can assume in the Catena-X data spaces is described in detail, along with its assigned description, responsibilities, relationships, prerequisites, and complements. Please refer to Chapter [What: Service Map](./../what-service-map/what-service-map.md) for an overview of the Service Map. ### Core Service Provider A **Role:** Core Service Provider A (CSP-A) -**Description/Responsibilities**: A CSP-A is responsible for deploying, operating, and maintaining core services A according to Catena-X standards. Core Services A provide common business functionalities for all data space participants (e.g., managing marketplace offers, semantic models, or searching for business partner information). +**Description/Responsibilities**: A CSP-A is responsible for deploying, operating, and maintaining core services A according to Catena-X standards. Core Services A provides common business functionalities for all data space participants (e.g., managing marketplace offers, semantic models, or searching for business partner information). A CSP-A can operate various bundles of Core Services A, whereby the operation of an IAM and a marketplace is mandatory. Note that the synchronization of marketplace offers is at the discretion of a provider, who may submit and list its offer on multiple marketplaces. The CSP-A role can be taken on by multiple participants. -For smooth operations, the CSP-A must provide comprehensive technical documentation, along with first, second, and third level support to facilitate integration with its services. Each CSP-A has freedom of choice regarding their business model towards their potential customers. +For smooth operations, the CSP-A must provide comprehensive technical documentation, along with first, second, and third-level support to facilitate integration with its services. Each CSP-A has freedom of choice regarding their business model towards their potential customers. **Relationships:** @@ -39,7 +39,7 @@ other CSP-As. - A CSP-A must accept and comply with the Catena-X regulatory framework during onboarding via one of the OSPs. -**Limitations Release 23.09:** +**Current Limitations:** - Due to technical limitations, the CSP-A role currently cannot be fully assumed and executed more than once. Further details can be found in Chapter [Increase Decentralization of Core Services](./../outlook/outlook.md#increase-decentralization-of-core-services) or can be requested during the conformity assessment. @@ -51,7 +51,7 @@ during onboarding via one of the OSPs. The CSP-B operates all Core Services B as one bundle to enable trusted participation and sovereign data exchange across all data space participants. The CSP-B role can only be taken on by one participant and is nominated by the Catena-X Association to operate and further develop the services on their behalf. -For smooth operations, the CSP-B must provide comprehensive technical documentation, along with first, second, and third level support to facilitate integration with its services. +For smooth operations, the CSP-B must provide comprehensive technical documentation, along with first, second, and third-level support to facilitate integration with its services. **Due to its special role, the CSP-B is responsible for:** @@ -65,45 +65,42 @@ For smooth operations, the CSP-B must provide comprehensive technical documentat - The CSP-B **must** support the integration of all other data space participants to the Core Services B. - A CSP-B **must** implement an IAM synchronization with CSP-As and OSPs. +- The CSP-B **must** integrate the GXDCH provided by the Catena-X Association. **Prerequisites:** - A CSP-B **must** be nominated by the Catena-X Association. - A CSP-B **must** be a Catena-X Association member. - A CSP-B and its services **must** be certified by a CAB. +- A CSP-B **must** offer a partnerRegistration API to any OSP requesting it - A CSP-B **must** accept and comply with the Catena-X regulatory framework via an MoU with the Association. -**Limitations Release 23.09:** +**Current Limitations:** - To ensure complete functionality of the data space, the CSP-B **must** also operate the relevant services of both the CSP-A and OSP roles. -- Further details can be found in Chapter [Increase Decentralization of Core Services](./../outlook/outlook.md#increase-decentralization-of-core-services). how Catena-X foster competition. +- Further details can be found in Chapter [Increase Decentralization of Core Services](./../outlook/outlook.md#increase-decentralization-of-core-services). ### Onboarding Service Provider **Role:** Onboarding Service Provider (OSP) -**Description/Responsibilities**: An OSP is responsible for deploying, operating, and maintaining onboarding services according to Catena-X standards. The onboarding services enable and support data space participants to register and onboard and offboard to Catena-X data space. +**Description/Responsibilities:** -This includes organizational registration and technical integration (see Chapter [General Onboarding](./../how-data-space-operations/how-data-space-operations.md#general-onboarding)), after which an organization can fully participate in the data space. An OSP can enable new prospects and/or their existing customer base in terms of network-of-networks. To ensure maximum trust in the data space during the onboarding process, the OSP must establish a connection with the Gaia-X Digital Clearing House (GXDCH). - -For smooth operations, the OSP must provide comprehensive technical documentation, along with first, second, and third level support to facilitate integration with its services. +OSPs are responsible for deploying, operating, and maintaining onboarding services according to Catena-X standards. These services facilitate the registration, onboarding, and offboarding of participants within the Catena-X data space. The OSP utilizes the CSP-B to validate data (e.g. name, address, identifier of the company) related to onboarding processes and must integrate with the `partnerRegistration` API of the CSP-B. This ensures that all data adheres to Catena-X standards and maintains the integrity and trustworthiness of the data space. The OSPs must provide comprehensive technical documentation and support (first, second, and third level) to facilitate the integration of services and assist users and other stakeholders. **Relationships:** -- An OSP **must** implement an IAM synchronization with CSP-As, the CSP-B, and OSPs to provide its customers with access to the data space. -- An OSP **must** integrate and use CSP-B services to access their identity(e. g., identity wallet) and enable data exchange. -- An OSP **must** integrate and use the GAIA-X Digital Clearing House to validate e. g., the Legal Person Self-Description. +- An OSP **must** integrate with the CSP-B to access the required endpoints. +- An OSP **must** implement an IAM synchronization with the CSP-B. **Prerequisites:** - An OSP and its services **must** be certified by a CAB. -- An OSP **must** integrate and use CSP-B services to access its identity (e. g., identity wallet) -- An OSP **must** accept and comply with the Catena-X regulatory framework during onboarding via one of the other OSPs. -- An OSP **must** use the dedicated GAIA-X Clearing House Service nominated by the Catena-X Association. +- An OSP **must** accept and comply with the Catena-X regulatory framework. -**Limitations Release 23.09:** +**Current Limitations:** -Due to technical limitations, the OSP role currently cannot be fully assumed and executed more than once. Further details can be found in Chapter [Increase Decentralization of Core Services](./../outlook/outlook.md#increase-decentralization-of-core-services) or can be requested during the conformity assessment. Offboarding will be included within the upcoming releases. +- Offboarding Processes Under Development: Comprehensive offboarding processes are currently in development to ensure that they are as robust as onboarding processes and will be included in future updates. Simple and manual offboarding processes are already available. ### Enablement Service Provider @@ -122,16 +119,16 @@ Catena-X semantic models. **Relationships:** -- An ESP **can** use one or more CSP-A services (e. g., semantic hub). -- An ESP **must** integrate and use CSP-B services to access its identity (e. g., identity wallet) and enable data exchange. -- An ESP **must** use the services of one of the OSPs to register and onboard itself to the data space (e. g., registration service). +- An ESP **can** use one or more CSP-A services (e.g., semantic hub). +- An ESP **must** integrate and use CSP-B services to access its identity (e.g., identity wallet) and enable data exchange. +- An ESP **must** use the services of one of the OSPs to register and onboard itself to the data space (e.g., registration service). **Prerequisites:** - An ESP and its services **must** be certified by a CAB. - An ESP **must** accept and comply with the Catena-X regulatory framework during onboarding via one of the OSPs. -**Limitations Release 23.09:** +**Current Limitations:** n/a @@ -146,9 +143,9 @@ them on one or multiple of the marketplaces **Relationships:** -- A BAP **can** use one or more CSP-A services (e. g., semantic hub). -- A BAP **must** integrate and use CSP-B services to access his identity (e. g., identity wallet) and enable data exchange. -- A BAP **must** use the services of one of the OSPs to register and onboard itself to the data space (e. g., registration service). +- A BAP **can** use one or more CSP-A services (e.g., semantic hub). +- A BAP **must** integrate and use CSP-B services to access his identity (e.g., identity wallet) and enable data exchange. +- A BAP **must** use the services of one of the OSPs to register and onboard itself to the data space (e.g., registration service). **Prerequisites:** @@ -156,7 +153,7 @@ them on one or multiple of the marketplaces - A BAP **must** list its solution on a marketplace provided by a CSP-A. - A BAP **must** accept and comply with the Catena-X regulatory framework during onboarding via one of the OSPs. -**Limitations Release 23.09:** +**Current Limitations:** n/a @@ -164,20 +161,20 @@ n/a **Role:** Advisory Provider (AP) -**Description/Responsibilities**: An AP offers advisory services in various areas, from strategy to operations to technology or business use cases for those interested in the Catena-X data space. Providing advisory services includes topics such as onboarding guidance, business value assessment, organizational and technical enablement, but do not include the operation of technical services. +**Description/Responsibilities**: An AP offers advisory services in various areas, from strategy to operations to technology or business use cases, for those interested in the Catena-X data space. Providing advisory services includes topics such as onboarding guidance, business value assessment, organizational and technical enablement, but does not include the operation of technical services. **Relationships:** - An AP **can** use one or more CSP-As if it intends to utilize specific CSP-A services such as listing an offer on a marketplace. - An AP **can** integrate and use CSP-B services to access the Core Services B. -- An AP **must** use the services of one of the OSPs to register and onboard itself to the data space (e. g., registration service). +- An AP **must** use the services of one of the OSPs to register and onboard itself to the data space (e.g., registration service). **Prerequisites:** - An AP **must** be qualified by the Catena-X Association. - An AP **must** accept and comply with the Catena-X regulatory framework during onboarding via one of the OSPs. -**Limitations Release 23.09:** +**Current Limitations:** n/a @@ -190,25 +187,26 @@ n/a **Relationships:** - A DPC **can** use the services of a CSP-A (e.g., marketplace). -- A DPC **must** integrate and use CSP-B services to access his identity (e. g., identity wallet) and enable data exchange. -- An DPC **must** use the services of one of the OSPs to register and onboard itself to the data space (e.g., registration service). This can be delegated to a BAP or ESP +- A DPC **must** integrate and use CSP-B services to access his identity (e.g., identity wallet) and enable data exchange. +- A DPC **must** use the services of one of the OSPs to register and onboard itself to the data space (e.g., registration service). This can be delegated to a BAP or ESP - A DPC **must** connect with another DPC to exchange data and create value. - A DPC **can** use advisory services from a qualified AP. -- A DPC **can** use certified enablement services from a commercial ESP (e.g., SaaS solution). Alternatively, a DPC can certify and operate its own enablement services. -- A DPC **can** use certified business applications from a commercial BAP (e.g., SaaS -solution). Alternatively, a DPC can certify and operate its own business application + +- A DPC **can** use certified enablement services from a commercial ESP (e.g., a SaaS solution). Alternatively, a DPC can certify and operate its own enablement services. +- A DPC **can** use certified business applications from a commercial BAP (e.g., a SaaS +solution). Alternatively, a DPC can certify and operate its own business application. **Prerequisites:** - A DPC **must** use certified enablement services or business applications. Alternatively, a DPC **must** certify its own enablement services and/or business applications by one of the CABs (as outlined in Chapter [Conformity Assessment](./../how-data-space-governance/how-data-space-governance.md#conformity-assessment)). - A DPC **must** accept and comply with the Catena-X regulatory framework during onboarding via one of the OSPs -**Limitations Release 23.09:** +**Current Limitations:** n/a *In addition to the roles in the data space, there are independent roles such as the Catena-X Association or Conformity -Assessment Bodies (CABs) to ensure neutral, trustworthy, and secure operation of the Catena-X data space.* +Assessment Bodies (CABs) to ensure the neutral, trustworthy, and secure operation of the Catena-X data space.* ### Catena-X Association @@ -228,22 +226,22 @@ Assessment Bodies (CABs) to ensure neutral, trustworthy, and secure operation of n/a -**Limitations Release 23.09:** +**Current Limitations:** -For the upcoming releases there will be a dedicated issuer concept in place. As of now the Association defines the Issuer (CSP-B). Further details can be found in Chapter [SSI Issuer Concept](./../how-data-space-operations/how-data-space-operations.md#ssi-issuer-concept). An outlook can be found in Chapter [Further Integration of SSI Technologies](./../outlook/outlook.md#further-integration-of-ssi-technologies). +For the upcoming releases, there will be a dedicated issuer concept in place. As of now, the Association defines the Issuer (CSP-B). Further details can be found in Chapter [SSI Issuer Concept](./../how-data-space-operations/how-data-space-operations.md#implementation-of-the-self-sovereign-identity-concept). An outlook can be found in Chapter [Further Integration of SSI Technologies](./../outlook/outlook.md#further-integration-of-ssi-technologies). ### Conformity Assessment Body **Role:** Conformity Assessment Body (CAB) -**Description/Responsibilities**: A CAB carries out the conformity assessment process in accordance with the Catena-X Certification Framework on behalf of the Catena-X Association. The Certification Framework consists of the certification manual and the certification catalog (derived from the ([Catena-X standards](https://catena-x.net/de/standard-library))). A CAB is nominated by the Catena-X Association to ensure an independent, trustworthy, and secure conformity assessment process. +**Description/Responsibilities**: A CAB carries out the conformity assessment process, in accordance with the Catena-X Certification Framework, on behalf of the Catena-X Association. The Certification Framework consists of the certification manual and the certification catalog (derived from the ([Catena-X standards](https://catenax-ev.github.io/docs/standards/overview))). A CAB is nominated by the Catena-X Association to ensure an independent, trustworthy, and secure conformity assessment process. **A CAB is responsible for:** - creating offers for the conformity assessments. - carrying out the conformity assessment process for various certification objects (e.g., provider, solutions). - informing the Catena-X Association and the certification candidate about the certification results. -- issuing, reissuing, and revoking of certificates on behalf of the Catena-X +- issuing, reissuing, and revoking certificates on behalf of the Catena-X Association. **Relationships:** @@ -254,8 +252,35 @@ participants and their IT solutions. **Prerequisites:** - A CAB must be nominated by the Catena-X Association and comply with the Catena-X certification framework. -- Business model supporting adoption and offering a non-discriminating access, esp. by small and medium business. +- Business model supporting adoption and offering non-discriminating access, esp. by small and medium businesses. -**Limitations Release 23.09:** +**Current Limitations:** n/a + +### Sandbox Provider (BETA) + +**Role:** Sandbox Provider (SP) + +**Description/Responsibilities**: + +A Sandbox Provider is responsible for deploying, operating, and maintaining a Catena-X Sandbox according to Catena-X standards. A Catena-X Sandbox includes all CSP-B and OSP components required to provide a functioning Catena-X operating environment see also Chapter [What-Service Map](./../what-service-map/what-service-map.md) for more details. An SP operates the Sandbox as one bundle of services to enable coherent testing of sovereign data exchange and services across all basic data space functionalities. Please take a look at the chapter Service map for a complete description of Catena-X Sandboxes. + +For smooth operations, an SP must provide comprehensive technical documentation and first, second, and third-level support to facilitate integration with its services. Each SP has freedom of choice regarding their business model towards their potential customers. + +Given that the Catena-X brand derives much of its value throug trust, Catena-X Sandboxes must only accept trusted users that went through the official Catena-X registration process via one of the OSPs, including the acceptance of the general Catena-X terms and conditions (10 golden rules, data exchange governance...). As Sandboxes are not directly linked to the Catena-X Operating Environment, a listing on the data space clearance list serve as proof for trusted users. + +**Relationships:** + +- An SP can operate independently from the CSP-B as Catena-X Sandboxes remain strictly separate from the Catena-X Operating Environment. +- An SP must only onboard trusted users, listed on the Catena-X data space clearance list. +- An SP must advertise a clear migration path to the productive Catena-X Operating Environment to its users. +- An SP must use the services of one of the OSPs to register and onboard itself to the data space (e.g., registration service). +- An SP must accept and comply with the Catena-X regulatory framework during onboarding via one of the OSPs. +- An SP offering its Sandbox to official Catena-X conformity assessment services must be nominated by the Catena-X Association. + +**Prerequisites and Limitations:** + +- As a BETA service, an SP and its services must not yet be certified by a CAB. Instead, operating a Catena-X Sandbox requires specific approval from the Catena-X Association and the signing of a self-assessment. +- Any approval granted to operate a Catena-X Sandbox is limited until October 2024. +- An SP is responsible for upholding certification verifications and checks for compliance with the Catena-X governance framework, given that a direct connection with the CSP-B is currently infeasible. Thereby, the Catena-X Association and the CSP-B are also not responsible or liable for any SLAs provided by the SP. diff --git a/docs/operating-model/why-introduction/_category_.json b/docs/operating-model/why-introduction/_category_.json index c476d7425..d2346ca1e 100644 --- a/docs/operating-model/why-introduction/_category_.json +++ b/docs/operating-model/why-introduction/_category_.json @@ -1,5 +1,5 @@ { - "label": "Who: Roles in the Catena-X ecosystem", + "label": "Why: Introduction", "position": 2, "collapsible": true, "collapsed": true diff --git a/docs/operating-model/why-introduction/why-introduction.md b/docs/operating-model/why-introduction/why-introduction.md index cb3e5b958..9367d4eba 100644 --- a/docs/operating-model/why-introduction/why-introduction.md +++ b/docs/operating-model/why-introduction/why-introduction.md @@ -5,13 +5,13 @@ sidebar_position: 1 ## Relevance -The Catena-X Operating Model Whitepaper is a normative document of the Catena-X Association. Normative documents outline rules, guidelines, and characteristics for activities and results for all participants within the Catena-X ecosystem. The Catena-X ecosystem includes Governance,Standardization,Certification,Development and Operations. These are established by consensus among the working groups and approved by the executive board of the Catena-X Association. As part of the Catena-X regulatory framework,this document is binding for all participants of the Catena-X ecosystem. This normative document is a foundational building block, allowing all participants to collaborate within a global ecosystem. +The Catena-X Operating Model Whitepaper is a normative document of the Catena-X Association. Normative documents outline rules, guidelines, and characteristics for activities and results for all participants within the Catena-X ecosystem. The Catena-X ecosystem includes Governance, Standardization, Certification, Development and Operations. These are established by consensus among the working groups and approved by the executive board of the Catena-X Association. As part of the Catena-X regulatory framework, this document is binding for all participants of the Catena-X ecosystem. This normative document is a foundational building block, allowing all participants to collaborate within a global ecosystem. ## Executive Summary ### Introduction -With Catena-X, the automotive industry is creating targets a trustworthy, collaborative, open, and secure data space to enable a data-driven value chain for their relevant business processes. All participants can be connected in business process-centric end-to-end value chains, where everyone operates on an equal playing field, has sovereign control over their data and no lock-in effects occur. Thereby, the digitalization of intercompany processes and value chains, especially those of small and medium-sized companies, can be performed on a cost effective, timely and lasting basis. Further, it secures that market participants and competitors collaborate in a compliant and trusted way. +With Catena-X, the automotive industry is creating targets for a trustworthy, collaborative, open, and secure data space to enable a data-driven value chain for their relevant business processes. All participants can be connected in business process-centric end-to-end value chains, where everyone operates on an equal playing field, has sovereign control over their data and no lock-in effects occur. Thereby, the digitalization of intercompany processes and value chains, especially those of small and medium-sized companies, can be performed on a cost-effective, timely, and lasting basis. Further, it ensures that market participants and competitors collaborate in a compliant and trusted way. ### Objectives @@ -19,8 +19,8 @@ This document defines the operating model and processes required within the Cate ### Scope -The Catena-X operating model describes the entire Catena-X ecosystem, focusing on the operating environment and its roles, processes, and solutions, and how they interact. Since Catena-X is under continuous development,the document refers, where appropriate, to dynamic content that can be found on the website of the Catena-X Association. +The Catena-X operating model describes the entire Catena-X ecosystem, focusing on the operating environment and its roles, processes, and solutions, and how they interact. Since Catena-X is under continuous development, the document refers, where appropriate, to dynamic content that can be found on the website of the Catena-X Association. ## Document updates -The Catena-X Association releases updates to its operating model in regular intervals to always guarantee a well-functioning, up-to-date framework for its data space operations. Updates are developed within the framework regulations of the Catena-X Association and require approval from the Association’s executive board. Every update of this operating model will automatically be applied to all Catena-X initiatives, existing participants, as well prospects, without further notice and individual approval. An update will be communicated in due time via the Catena-X Association. +The Catena-X Association releases updates to its operating model in regular intervals to always guarantee a well-functioning, up-to-date framework for its data space operations. Updates are developed within the framework regulations of the Catena-X Association and require approval from the Association’s executive board. Every update of this operating model will automatically be applied to all Catena-X initiatives, existing participants, and doesn't require individual approval. An update will be communicated in due time via the Catena-X Association. diff --git a/docs/operating-model/why-understanding-the-catena-x-data-space/assets/the-catena-x-data-space.png b/docs/operating-model/why-understanding-the-catena-x-data-space/assets/the-catena-x-data-space.png index af5303351..d0e0a71f9 100644 Binary files a/docs/operating-model/why-understanding-the-catena-x-data-space/assets/the-catena-x-data-space.png and b/docs/operating-model/why-understanding-the-catena-x-data-space/assets/the-catena-x-data-space.png differ diff --git a/docs/operating-model/why-understanding-the-catena-x-data-space/assets/why-understanding-the-catena-x-data-space.pptx b/docs/operating-model/why-understanding-the-catena-x-data-space/assets/why-understanding-the-catena-x-data-space.pptx new file mode 100644 index 000000000..8410844a7 Binary files /dev/null and b/docs/operating-model/why-understanding-the-catena-x-data-space/assets/why-understanding-the-catena-x-data-space.pptx differ diff --git a/docs/operating-model/why-understanding-the-catena-x-data-space/why-understanding-the-catena-x-data-space.md b/docs/operating-model/why-understanding-the-catena-x-data-space/why-understanding-the-catena-x-data-space.md index 8d2b68fa8..3126ee0d5 100644 --- a/docs/operating-model/why-understanding-the-catena-x-data-space/why-understanding-the-catena-x-data-space.md +++ b/docs/operating-model/why-understanding-the-catena-x-data-space/why-understanding-the-catena-x-data-space.md @@ -10,35 +10,36 @@ To comprehend the components that comprise the Catena-X operating model, it is n ![Catena-X Data Ecosystem](./assets/catena-x-data-ecosystem.png) *Catena-X Data Ecosystem* -The **Catena-X Automotive Network e. V.** (in the following called “Catena-X Association” or “the Association”) is responsible for standardization, certifications, and governance of the Catena-X ecosystem. Members can participate in committees, working groups, and expert groups to actively shape the Catena-X ecosystem. The Catena-X Association publishes standards with the goal of enabling interoperability, data-sovereignty, and security for all participants in the data space. The ecosystem participants must comply with the standards published by the Catena-X Association to work with the data space. Catena-X standards build on Gaia-X/Inter-national Data Space Association (IDSA) concepts and principles, industry standards, and best practices, among others, and extends these by automotive domain and use case-specific requirements. By certifying ecosystem participants and software components, the Catena-X Association ensures transparency and trust in the eco- system. A certification testifies, for example, that a software component is interoperable, data sovereign, and safe to use in the Catena-X data space. The Association is complemented by the **development environment**. The focus of the development environment is on the one hand on the creation of standardization candidates that can be submitted into the standardization process of the association. And on the other hand, the development of open-source reference implementations and other implementations for the data space. In the **operating environment**, the various open-source and commercial services and business applications are operated by different providers. A detailed description of the provider roles and the associated software components can be found in **Chapter [Who: Roles in the Catena-X Ecosystem](./../who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md)** and **Chapter [What: Service Map](./../what-service-map/what-service-map.md)**. All three components jointly make up the Catena-X data ecosystem. In the following chapters, the roles, responsibilities, and functions of these components are described in detail. +The **Catena-X Automotive Network e. V.** (in the following called “Catena-X Association” or “the Association”) is responsible for standardization, certifications, and governance of the Catena-X ecosystem. Members can participate in committees, working groups, and expert groups to actively shape the Catena-X ecosystem. The Catena-X Association publishes standards with the goal of enabling interoperability, data sovereignty, and security for all participants in the data space. The ecosystem participants must comply with the standards published by the Catena-X Association to work with the data space. Catena-X standards build on Gaia-X/International Data Space Association (IDSA) concepts and principles, industry standards, and best practices, among others, and extend these to the automotive domain and use case-specific requirements. By certifying ecosystem participants and software components, the Catena-X Association ensures transparency and trust in the ecosystem. A certification testifies, for example, that a software component is interoperable, data sovereign, and safe to use in the Catena-X data space. The Association is complemented by the **development environment**. The focus of the development environment is on the one hand, on the creation of standardization candidates that can be submitted into the standardization process of the association. On the other hand, the development of open-source reference implementations and other implementations for the data space. In the **operating environment**, the various open-source and commercial services and business applications are operated by different providers. A detailed description of the provider roles and the associated software components can be found in Chapter [Who: Roles in the Catena-X Ecosystem](./../who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md) and Chapter [What: Service Map](./../what-service-map/what-service-map.md). All three components jointly make up the Catena-X data ecosystem. In the following chapters, the roles, responsibilities, and functions of these components are described in detail. ## The Catena-X Data Ecosystem Architecture Underlining the Catena-X data ecosystem’s conceptual foundations are its individual data space components. Together, these building blocks serve as the architecture of the Catena-X data space, where each building block serves a dedicated purpose in one or several of the above-mentioned conceptual elements. An overview is depicted in Figure [Catena-X Data Ecosystem](#the-catena-x-data-ecosystem-architecture) followed by a short description of the main building blocks. -![The Catena-X Data Space](./assets/the-catena-x-data-space.png) +![The Catena-X Data Space](./assets/the-catena-x-data-space.png) *Catena-X Data Ecosystem* The global Catena-X data space is built on 5 mission-critical pillars: -- a dedicated **role concept** covering all data space participants (see **Chapter [Who: Roles in the Catena-X Ecosystem](./../who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md)**) -- a Service Map of foundational software services, building blocks, and standards that form the **Catena-X Operating System** and **Business Foundation** (see **Chapter [What: Service Map](./../what-service-map/what-service-map.md)**), -- procedures, processes, and building blocks for a trusted, scalable, and compliant **data space operation** (see **Chapter [How: Data Space Operations](./../how-data-space-operations/how-data-space-operations.md)**), -- effective **data space governance** incl. standards, legal frameworks, (flight models) and certification (see **Chapter [How: Data Space Governance](./../how-data-space-governance/how-data-space-governance.md)**) -- an integrated and holistic **life cycle management ensuring compliance, interoperability**, and **compatibility** (see **Chapter [How: Life Cycle Management](./../how-life-cycle-management/how-life-cycle-management.md)**) +- a dedicated **role concept** covering all data space participants (see Chapter [Who: Roles in the Catena-X Ecosystem](./../who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md)) +- a Service Map of foundational software services, building blocks, and standards that form the **Catena-X Operating System** and **Business Foundation** (see Chapter [What: Service Map](./../what-service-map/what-service-map.md)), +- procedures, processes, and building blocks for a trusted, scalable, and compliant **data space operation** (see Chapter [How: Data Space Operations](./../how-data-space-operations/how-data-space-operations.md)), +- effective **data space governance** incl. standards, legal frameworks, (flight levels) and certification (see Chapter [How: Data Space Governance](./../how-data-space-governance/how-data-space-governance.md)) +- an integrated and holistic **life cycle management ensuring compliance, interoperability**, and **compatibility** (see Chapter [How: Life Cycle Management](./../how-life-cycle-management/how-life-cycle-management.md)) -To promote adoption and collaboration, the Catena-X data space is built upon open-source principals, under the umbrella of the Eclipse Foundation. All Catena-X reference implementations and KITs are licensed under Apache 2.0 and CY BB 4.0. In order to structure and guide the development in open-source, Catena-X installed Organizational Elements (e.g., committees in the Catena-X Association), created a working group and project in Eclipse Tractus-X and defined a scalable structure for a business-oriented development and adoption of relevant artifacts and SW codes: +To promote adoption and collaboration, the Catena-X data space is built upon open-source principles, under the umbrella of the Eclipse Foundation. All Catena-X reference implementations and KITs are licensed under Apache 2.0 and CY BB 4.0. In order to structure and guide the development in open-source, Catena-X installed Organizational Elements (e.g., committees in the Catena-X Association), created a working group and project in Eclipse Tractus-X and defined a scalable structure for a business-oriented development and adoption of relevant artifacts and software codes: -- Enablement Services -- Core Services +- Enablement Services, +- Core Services, +- Onboarding Services - Industry Core - and use case KITs -With regard to standardization, the Catena-X Association promotes, sponsors and coordinates the overarching requirements of the Eclipse Tractus-X project. Standards are always linked, structured, and offered within those four elements. +With regard to standardization, the Catena-X Association promotes, sponsors, and coordinates the overarching requirements of the Eclipse Tractus-X project. Standards are always linked, structured, and offered within those four elements. -Catena-X offers use case KITs to enable a multi-vender ecosystem of software solutions and services for each Catena-X use case. Solution and Service providers can create interoperable and data sovereign solutions and trusted services based on the Catena-X KITs and offer them on trusted marketplaces within the Catena-X Data Space (-> Core Service Provider A). The marketplaces are certified marketplaces that offer interoperable solutions from different solutions providers. The Core Services as well as marketplaces are part of the cxOS and are operated by certified operating companies (see Figure [Service Map](./../what-service-map/what-service-map.md)). With this comprehensive solution portfolio, players in the automotive value chain can create business value by establishing data-driven use cases and data chains. +Catena-X offers use case KITs to enable a multi-vendor ecosystem of software solutions and services for each Catena-X use case. Solution and Service providers can create interoperable and data sovereign solutions and trusted services based on the Catena-X KITs and offer them on trusted marketplaces within the Catena-X Data Space ([Who: Roles in the Catena-X Ecosystem](./../who-roles-in-the-catena-x-ecosystem/who-roles-in-the-catena-x-ecosystem.md)). The marketplaces are certified marketplaces that offer interoperable solutions from different solution providers. The Core Services as well as marketplaces are part of the cxOS and are operated by certified operating companies (see Figure [Service Map](./../what-service-map/what-service-map.md)). With this comprehensive solution portfolio, players in the automotive value chain can create business value by establishing data-driven use cases and data chains. -Trust and conformity (of Services, Offers, and potentially other non-automotive data spaces) are fundamental for Catena-X’s acceptance, scalability, and value creation. Therefore, Catena-X chose and installed various neutral governance bodies – covering development and operation. The following partnerships and components in sum ensure a global data space built by best-in-class experts on trusted principles: +Trust and conformity (of services, offers, and potentially other non-automotive data spaces) are fundamental for Catena-X’s acceptance, scalability, and value creation. Therefore, Catena-X chose and installed various neutral governance bodies – covering development and operation. The following partnerships and components, in sum, ensure a global data space built by best-in-class experts on trusted principles: 1. Gaia-X is the basis for our overarching Trust Framework and forms the foundation for a federated, interoperable data space with trusted identities. @@ -48,4 +49,28 @@ Trust and conformity (of Services, Offers, and potentially other non-automotive 4. The Catena-X Association provides industry-specific governance for the ecosystem that equally reflects the diverse interest groups within the automotive industry to serve common business needs. It also defines the vision, mission, and guiding principles for the Catena-X data space through the governance framework based on the Catena-X Statutes. -More specifically, in the **Catena-X operating environment**, the Catena-X Regulatory Framework for Data Space operations acts as a reliable mutual foundation to ensure trust, interoperability and therefore scalability. Catena-X’s success largely depends on trust that every participant plays by the same, commonly set rules. By standardizing many of the relationships and agreements necessary for data exchange and bringing Catena-X use cases to life, data space participants can put their focus largely on their individual business needs rather than individual contract negotiation between business partners. Through collectively approved guidelines and templates, data exchanges on Catena-X can be seamlessly executed and operated without friction. +More specifically, in the **Catena-X operating environment**, the Catena-X Regulatory Framework for Data Space operation model as a reliable mutual foundation to ensure trust, interoperability, and therefore scalability. Catena-X’s success largely depends on trust that every participant plays by the same, commonly set rules. By standardizing many of the relationships and agreements necessary for data exchange and bringing Catena-X use cases to life, data space participants can put their focus largely on their individual business needs rather than individual contract negotiation between business partners. Through collectively approved guidelines and templates, data exchanges on Catena-X can be seamlessly executed and operated without friction. + +## Data Space Interoperability + +Efforts toward achieving interoperability with and within Catena-X are integral to its success. Interoperability ensures seamless communication and interaction between various participants within the wider industry ecosystem. In alignment with the European Interoperability Framework, which defines and divides interoperability into legal, organizational, semantic, and technical interoperability, Catena-X pursues a comprehensive approach to ensure compatibility and harmonization across the entire automotive value chain. + +Therefore, Catena-X aims at creating an interoperable data space, so that participants from closely related data spaces and industry ecosystems can choose to access data, services, and applications from selected partners in another data space without additional technical, organizational, or legal burdens. + +This enables participants of the Catena-X data space, who are active in multiple data spaces to realize additional business value by connecting to partners beyond their own network and allows a simplified onboarding process. + +1. **Technical Interoperability:** + + Technical interoperability addresses the compatibility towards the Catena-X systems, interfaces, and protocols used for data exchange within the data space. The minimum requirement to achieve interoperability with Catena-X is adopting the Data Spaces Protocol (DSP) and Identity and Trust Protocol (IATP). Data spaces provide the basis of our technical interoperability and Catena-X embraces open technological convergence and best practices to ensure seamless integration and connectivity across many data spaces. The DSP serves similarly to the ASS as one example of industry standards that can be used to ensure technical interoperability of multiple data spaces. Additionally, the Tractus-X development environment, facilitated by the Eclipse Foundation, fosters the creation of interoperable software components like the EDC and reference implementations, promoting innovation and flexibility in system design and implementation. + +2. **Semantic Interoperability:** + + Semantic interoperability ensures a common understanding and interpretation of data exchanged with and within the Catena-X data space. The Catena-X Ecosystem therefore utilizes semantic models based on the Semantic Aspect Meta Model (SAMM), an open and standardized specification for Aspect Models. Additionally, Catena-X also employs the internationally widely adopted Asset Administration Shell (AAS) as one technical implementation. The ASS supports the standard-compliant exchange of data along the entire production life cycle. Employing these models is again the minimum requirement to achieve semantic interoperability with Catena-X. Within this context, standardization efforts led by the Association, in collaboration with industry partners like the IDTA, aim to establish shared vocabularies, ontologies, and data models specific to automotive domains and use cases. + +3. **Legal Interoperability:** + + Catena-X operates within a regulatory framework that establishes rights, responsibilities, and obligations governing data exchange and usage. At the most basic level, contracts need to allow potential addendum that enable the exchange with partners from other data spaces while ensuring compliance of such external data space partners with the Catena-X regulatory framework e.g. the country clearance list, the 10 golden rules, etc. To allow for a more seamless transition between Catena-X and other data spaces, compliance with the Catena-X regulatory framework should be integrated at the data space level of such external data spaces. + +4. **Organizational Interoperability:** + + Organizational interoperability focuses on aligning key structures, processes, and roles across diverse stakeholders. The minimum effort to achieve organizational interoperability with Catena-X means to acknowledge the Catena-X Governance and its essential roles. This indicates that by employing Catena-X CSPs and OSPs, it's easier to access our data space effortlessly. In general, the Association plays a central role in fostering collaboration also with other initiatives like Gaia-X, IDSA, and the Eclipse Data Space Working Group. diff --git a/docs/regulatory-framework/change-log.md b/docs/regulatory-framework/changelog.md similarity index 79% rename from docs/regulatory-framework/change-log.md rename to docs/regulatory-framework/changelog.md index bebab61e3..605bcb4c3 100644 --- a/docs/regulatory-framework/change-log.md +++ b/docs/regulatory-framework/changelog.md @@ -2,6 +2,7 @@ pagination_prev: null pagination_next: null sidebar_position: 5 +sidebar_class_name: separator-top --- # Change Log diff --git a/docs/standards/CX-0001-EDCDiscoveryAPI/CX-0001-EDCDiscoveryAPI.md b/docs/standards/CX-0001-EDCDiscoveryAPI/CX-0001-EDCDiscoveryAPI.md new file mode 100644 index 000000000..740283b42 --- /dev/null +++ b/docs/standards/CX-0001-EDCDiscoveryAPI/CX-0001-EDCDiscoveryAPI.md @@ -0,0 +1,510 @@ +# CX-0001 EDC Discovery API v1.0.2 + +## ABSTRACT + +The definition and introduction of a cross-industry standard for the discovering of EDC instances is crucial for the networking of OEMs, suppliers, consumers, and industrial partners to automatically look up services and data. In a high competing eco systems data are the new oil. Even meta data on data offerings can provide business sensitive information. Hence even meta data for data offerings will be secured via an EDC endpoint. + +As the Catena-X network expands, a sizable amount of data assets will be available via EDC connection technology. It could be difficult to efficiently identify the proper EDC endpoint within the network. + +To be GAIA-X compliant each EDC endpoint must provide a Self Description (SD) of type ServiceOffering. Based on these SD a Data & Service Discovery Service must be provided to easily look up suitable EDC instances to query data offerings efficiently. + +## 1. Introduction + +Participants do not want their personal information made public. As a +result, these may only be searched indirectly, which necessitates +knowing or establishing who the data should be obtained from. Because no +one wants to examine every EDC instance (load of the net, latency +becomes ever larger with increasing number of participants, procedure +does not scale thus). As a result, the number of EDC instances requested +must be limited by suitable filters. As a result, subscribers must first +determine who may have the data depending on their specific +circumstances. This is performed by utilizing the EDC discovery service. +The Business Partner Number (BPN) is currently the only criterion +provided for restricting the EDC instances in question. + +This standard has not the scope and intention to be a general solution +pattern to search and discover any service and data offer. It is limited +to look up the EDC instance in front of these service and data +offerings. + +### 1.1 Audience & Scope + +> *This section is non-normative* + +This standard is relevant for the following roles: + +- Data Provider / Consumer +- Business Application Provider +- Core Service Provider +- Onboarding Service Provider +- Enablement Service Provider + +For now, the EDC Discovery API is limited to filter suitable EDC +instances based on BPN number providing data and service offerings. This +document describes the relevant API endpoint to be created by an +operating company to enable EDC discovery by supported criterions +(currently on the BPN number). + +### 1.2 Context + +> *This section is non-normative* + +The EDC Discovery API is used to search and find service and data +offerings. In a network of network this is the most crucial topic to +build value added data services and data chains. + +### 1.3 Architecture Overview + +> *This section is non-normative* + +![CX-0001-main-components.png](./assets/CX-0001-main-components.png) + +Figure 2 Main Components + +In Figure 2 a high-level overview of the EDC Discovery Service workflow +is sketched. Both connectors must be registered within an identity +provider providing Verifiable Credentials (VC) to prove their identity by e.g. a Managed Identity Wallet (MIW). Any +data provider can register assets and expose them to a metadata broker +(Federated Catalog) for other consuming connectors to find. For +registration Self Descriptions of Type LegalPerson and ServiceOffering +for the providing EDC instance must be registered at the federated +catalog. Via EDC Discovery Service the EDC instance can be queried via +BPN number, which is part of the SD artifacts. Finally, the consumer can +obtain contract offers from the provider and begin contract +negotiations. + +The federated Catalog will be the storage of SD and the EDC Discovery Service the query API to retrieve URL of EDC instance of interest. There is no longer a central Digital Twin Registry (DTR) available from core service, but decentral instances (DDTR) hidden behind a data providing EDC. Hence any consumer has to identify the providing EDC to get access to the DDTR behind that EDC. + +### 1.4 Conformance + +As well as sections marked as non-normative, all authoring guidelines, +diagrams, examples, and notes in this specification are non-normative. +Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, +SHOULD and SHOULD NOT in this document are to be interpreted as +described in [BCP +14](https://datatracker.ietf.org/doc/html/bcp14) \[[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)\] +\[[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)\] when, and +only when, they appear in all capitals, as shown here. + +### 1.5 Proof of conformity + +All participants and their solutions will need to proof, that they are +conform with the Catena-X standards. To validate that the standards are +applied correctly, Catena-X employs Conformity Assessment Bodies +(CABs). + +- The Service Operator **MUST** provide an onboarding process for + participants and EDC instances. According to CX - 0006 Registration + and initial onboarding + +- The implemented service **MUST** use an SD storage like SD-Hub or + Federated Catalogue for storing the SD documents provided during the + onboarding process. + +- The provided SD documents **MUST** be GAIA-X compliant, i.e. **MUST** + provide a compliance credential issued from GAIA-X AIBSL. + +- The implemented service **SHOULD** use the SD storage as source of + truth. + +A test case could be, that an EDC instance has to be onboarded for a specific participant identified by a BPN. The SD for the EDC has to be visible in the supported SD storage (currently central hosted by the Core Service Provider). The SD documents has to be accessible by the dataspace participants. + +### 1.6 Examples + +**SD for Legal Person** + +``` +{ + +\"id\": , + +\"@context\": \[ + +, + +, + +, + + + +\], + +\"type\": \[ + +\"VerifiableCredential\", + +\"LegalPerson\" + +\], + +\"issuer\": \"did:sov:Bq3Nk9Z7sT8KeqNCnG4PrB\", + +\"issuanceDate\": \"2022-09-23T23:23:23.235Z\", + +\"credentialSubject\": { + +\"ctxsd:bpn\": \"1234\", + +\"id\": \"did:web:compliance.gaia-x.eu\", + +\"gx-participant:name\": \"Gaia-X AISBL\", + +\"gx-participant:legalName\": \"Gaia-X European Association for Data and +Cloud AISBL\", + +\"gx-participant:registrationNumber\": { + +\"gx-participant:registrationNumberType\": \"local\", + +\"gx-participant:registrationNumberNumber\": \"0762747721\" + +}, + +\"gx-participant:headquarterAddress\": { + +\"gx-participant:addressCountryCode\": \"BE\", + +\"gx-participant:addressCode\": \"BE-BRU\", + +\"gx-participant:streetAddress\": \"Avenue des Arts 6-9\", + +\"gx-participant:postalCode\": \"1210\" + +}, + +\"gx-participant:legalAddress\": { + +\"gx-participant:addressCountryCode\": \"BE\", + +\"gx-participant:addressCode\": \"BE-BRU\", + +\"gx-participant:streetAddress\": \"Avenue des Arts 6-9\", + +\"gx-participant:postalCode\": \"1210\" + +}, + +\"gx-participant:termsAndConditions\": +\"70c1d713215f95191a11d38fe2341faed27d19e083917bc8732ca4fea4976700\" + +}, + +\"credentialStatus\": { + +\"id\": +, + +\"type\": \"StatusList2021Entry\", + +\"statusPurpose\": \"revocation\", + +\"statusListIndex\": \"7\", + +\"statusListCredential\": + + +}, + +\"proof\": { + +\"type\": \"Ed25519Signature2018\", + +\"created\": \"2023-02-08T14:12:12Z\", + +\"proofPurpose\": \"assertionMethod\", + +\"verificationMethod\": \"did:sov:Bq3Nk9Z7sT8KeqNCnG4PrB#key-1\", + +\"jws\": +\"eyJhbGciOiAiRWREU0EiLCAiYjY0IjogZmFsc2UsICJjcml0IjogWyJiNjQiXX0..E4x-UYAS6d4UqK6cuaRLzJ4ZgZxUZL6NrMZePmqPZjt5XckcYU7HK1iTV9OuBJxj8YkeZxWCYsC4E5QkeliOCg\" + +}, + +> {\ +> \"complianceCredential\": {\ +> \"@context\": \[\"https://www.w3.org/2018/credentials/v1\"\],\ +> \"type\": \[\"VerifiableCredential\", \"ParticipantCredential\"\],\ +> \"id\": +> \"https://catalogue.gaia-x.eu/credentials/ParticipantCredential/1664629337488\",\ +> \"issuer\": \"did:web:compliance.gaia-x.eu\",\ +> \"issuanceDate\": \"2022-10-01T13:02:17.489Z\",\ +> \"credentialSubject\": {\ +> \"id\": \"did:web:compliance.gaia-x.eu\",\ +> \"hash\": +> \"3280866b1b8509ce287850fb113dc76d1334959c759f82a57415164d7a3a4026\"\ +> },\ +> \"proof\": {\ +> \"type\": \"JsonWebSignature2020\",\ +> \"created\": \"2022-10-01T13:02:17.489Z\",\ +> \"proofPurpose\": \"assertionMethod\",\ +> \"jws\": +> \"eyJhbGciOiJQUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YQAIjkqX6OL4U3efV0zumn8-l8c4wQo98SOSlzt53HOR8qlLu5L5lmwZJnAsR7gKW-6jv5GBT0X4ORQ1ozLvihFj6eaxxJNgzLFPoH5w9UEaEIO8mMGyeQ-YQYWBbET3IK1mcHm2VskEsvpLvQGnk6kYJCXJzmaHMRSF3WOjNq_JWN8g-SldiGhgfKsJvIkjCeRm3kCt_UVeHMX6SoLMFDjI8JVxD9d5AG-kbK-xb13mTMdtbcyBtBJ_ahQcbNaxH-CfSDTSN51szLJBG-Ok-OlMagHY_1dqViXAKl4T5ShoS9fjxQItJvFPGA14axkY6s00xKVCUusi31se6rxC9g\",\ +> \"verificationMethod\": \"did:web:compliance.gaia-x.eu\"\ +> }\ +> }\ +> } + +} +``` + +**SD for ServiceOffering** + +``` +"**"{ + "**\ +**\""selfDescriptionCredential\": {**\ +**\"@context\": \[**\ +**\"https://www.w3.org/2018/credentials/v1\",**\ +**\"https://registry.gaia-x.eu/v2206/api/shape\"**\ +**\],**\ +**\"type\": \[**\ +**\"VerifiableCredential\",**\ +**\"ServiceOfferingExperimental\"**\ +**\],**\ +**\"id\": +\"https://compliance.gaia-x.eu/.well-known/serviceComplianceService.json\",**\ +**\"issuer\": \"did:web:delta-dao.com\",**\ +**\"issuanceDate\": \"2022-09-25T23:23:23.235Z\",**\ +**\"credentialSubject\": {**\ +**\"id\": +\"https://compliance.gaia-x.eu/.well-known/serviceComplianceService.json\",**\ +**\"gx-service-offering:providedBy\": +\"https://compliance.gaia-x.eu/.well-known/participant.json\",**\ +**\"gx-service-offering:name\": \"Gaia-X Lab Compliance Service\",**\ +**\"gx-service-offering:description\": \"The Compliance Service will +validate the shape and content of Self Descriptions. Required fields and +consistency rules are defined in the Gaia-X Trust Framework.\",**\ +**\"gx-service-offering:webAddress\": +\"https://compliance.gaia-x.eu/\",**\ +**\"gx-service-offering:termsAndConditions\": \[**\ +**{**\ +**\"gx-service-offering:url\": +\"https://compliance.gaia-x.eu/terms\",**\ +**\"gx-service-offering:hash\": \"myrandomhash\"**\ +**}**\ +**\],**\ +**\"gx-service-offering:gdpr\": \[**\ +**{**\ +**\"gx-service-offering:imprint\": \"https://gaia-x.eu/imprint/\"**\ +**},**\ +**{**\ +**\"gx-service-offering:privacyPolicy\": +\"https://gaia-x.eu/privacy-policy/\"**\ +**}**\ +**\],**\ +**\"gx-service-offering:dataProtectionRegime\": \[**\ +**\"GDPR2016\"**\ +**\],**\ +**\"gx-service-offering:dataExport\": \[**\ +**{**\ +**\"gx-service-offering:requestType\": \"email\",**\ +**\"gx-service-offering:accessType\": \"digital\",**\ +**\"gx-service-offering:formatType\": \"mime/png\"**\ +**}**\ +**\],**\ +**\"gx-service-offering:dependsOn\": \[**\ +**\"https://compliance.gaia-x.eu/.well-known/serviceManagedPostgreSQLOVH.json\",**\ +**\"https://compliance.gaia-x.eu/.well-known/serviceManagedK8sOVH.json\"**\ +**\],** + +**""ctxsd":"connector-url\"": ""https":"\"**\ +**},**\ +**\"proof\": {**\ +**\"type\": \"JsonWebSignature2020\",**\ +**\"created\": \"2022-09-25T22:36:50.274Z\",**\ +**\"proofPurpose\": \"assertionMethod\",**\ +**\"verificationMethod\": \"did:web:compliance.gaia-x.eu\",**\ +**\"jws\": +\"eyJhbGciOiJQUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..Chbzpl0-4S3sobkKXyBjfx6pm74xLHInOmruHUmO\--3HpMcrfKldeJQPYLrUWsEJ1HIjMUqxE6QymZRxXfuRlAJKy2nwyM3S5sFX9YJ8bepBcf6q-nWGTDX-jh8wuyX3lwrG94aJnTBByKPLCovSiZ9BURR3cwiSHczBlM7iP90ee5roHOtI-eoqSBYrYaynTaK5eQaWfT-2OdXYgqVPSRJAK2KD5AqEM8KU7x6nnP6-shgSNBIEC1fAOTfAEUYkcrK8Tn4BTaH02HnO3B90S1MWyAWwBzrnmS915CFY4BiHsp9Tz7pt016c8HB8HE7gqoXndk7DUhzgNE2mRbHuLg\"**\ +**}**\ +**},**\ +**\"complianceCredential\": {**\ +**\"@context\": \[**\ +**\"https://www.w3.org/2018/credentials/v1\"**\ +**\],**\ +**\"type\": \[**\ +**\"VerifiableCredential\",**\ +**\"ServiceOfferingCredentialExperimental\"**\ +**\],**\ +**\"id\": +\"https://catalogue.gaia-x.eu/credentials/ServiceOfferingCredentialExperimental/1664145414932\",**\ +**\"issuer\": \"did:web:compliance.gaia-x.eu\",**\ +**\"issuanceDate\": \"2022-09-25T22:36:54.932Z\",**\ +**\"credentialSubject\": {**\ +**\"id\": +\"https://compliance.gaia-x.eu/.well-known/serviceComplianceService.json\",**\ +**\"hash\": +\"eeac8a9b5b6750f13fbc548299b22b73d6beea13f19e71856d0027b5cd42069c\"**\ +**},**\ +**\"proof\": {**\ +**\"type\": \"JsonWebSignature2020\",**\ +**\"created\": \"2022-09-25T22:36:54.932Z\",**\ +**\"proofPurpose\": \"assertionMethod\",**\ +**\"jws\": +\"eyJhbGciOiJQUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..SibPFxPtfsKP439SjoKo5VtmU_EpgsfuEjghCt_8sG2fUYT6s9CTY8jyEniGUkk7BIWnIYNsuuKudlNBD27kwzdTy6bZX9Jq0OaAaCpgZAZ9vlp7oFZF3ysLcERmBAixzGUjL0sny06Mu7IRCcDYVhLyd6flOvUGtH2I6T9u6UZL8cN1advRYKd4BSumAp5d4cCG-7cg7DCqPXk_M8cTvU8mDeXvXfciv7sIqvkwqd2L-T4kbxmPTCY3r3wPoVHGBDa3Gnntwkz3_aVInjbztchH-WmlDpCPv1hTv4uZNenNZVw7xsx1_o0voJJLSGtlYNhW4rk2oDxr4qie3S-Zgw\",**\ +**\"verificationMethod\": \"did:web:compliance.gaia-x.eu\"**\ +**}**\ +**}**\ +**}**" +``` + +### 1.7 Terminology + +> *This section is non-normative* + +The following terms are especially relevant for the understanding of the +standard: + +**Business Partner Number (BPN)** + +A BPN is the unique identifier of a partner within Catena-X. + +**Self Description (SD)** + +Gaia-X requires all providers to describe themselves and their service +offerings using standardized, machine-readable metadata called +Self-Descriptions. Such Self-Descriptions will for example include +information like the address of a company, a specific service +description or certificates and labels. + +Additional terminology used in this standard can be looked up in the +glossary on the association homepage. + +## 2 EDC Discovery API + +> *This section is normative* + +The EDC discovery service **MUST** be offered as central available endpoint by the Core Service Provider. +Every EDC registered in the network **MUST** be registered in the EDC discovery service. Therefore the needed workflows/processes (as defined in CX - 0006 Registration and initial onboarding) **MUST** be followed/implemented. + +The EDC discovery endpoint can get triggered via technical as well as +real users, if relevant roles are available. + +For technical user, a company can request the user creation with the +technical user creation feature inside the portal. + +All participants and their solutions will need to proof, that they are +conform with the Catena-X standards. To validate that the standards are +applied correctly, Catena-X employs Conformity Assessment Bodies +(CABs). + +- The Core Service Provider **MUST** offer a process/workflow to register dataspace connectors (as defined in CX - 0006 Registration and initial onboarding); Enablement Service Provider as well as Application Service Provider **MUST** run the connector registration for their service customers. + +- SD documents **MUST** be created for every Connector registered and stored by the Participants. The Core Service Provide make them available. + +- The provided SD documents **MUST** be GAIA-X compliant, i.e. MUST + provide a compliance credential issued from GAIA-X AIBSL. + +A test case will be, that an EDC instance has to be onboarded for a +specific participant identified by a BPN. The SD for the EDC has to be +visible in the supported SD storage. The query against this new +registered EDC instance for the given BPN **SHOULD** provide the connector +url as stated in the SD document. + +## 2.1 Preconditions and dependencies + +The self-description documents used as data source **MUST** be GAIA-X +compliant, i.e. adhering to the GAIA-X Trustframework in the currently +supported version in Catena-X (usually the latest published version and +the version before). In addition, these SD documents **MUST** be registered +at an SD storage like SD-Hub or Federated Catalogue. + +## 2.2 API Specification + +### 2.2.1 API Endpoints & resources + +The EDC Discovery API **MUST** be implemented as specified in the openAPI +documentation as stated here: https://\.... + +Endpoint: POST: /api/administration/connectors/discovery + +**Request body** + +the request body can be kept empty (to retrieve a complete list of registered connectors) or be filled with one or multiple BPNs to retrieve a list of registered EDC endpoints for the giving BPNs. + +``` +*\[* + +*"BPNL\...\...",* + +*"BPNL\...."* + +*\]* +``` + +**Response structure** + +``` +\[ + +{ + +"bpn : "BPNL\...\..." + +"connectorEndpoint": + +\[ + +"http://some.example.url", + +"http://some.other-example.url" + +\] + +}, + +{ + +"bpn : "BPNL\...\..." + +"connectorEndpoint": "http://some.example.url" + +} + +\] +``` + +For each bpn an own response object is provided. In case of multiple EDC +instances for one bpn an array is returned (first result set) otherwise +a single value (second result set) + +### 2.2.2 Available Data Types + +The API MUST use JSON as the payload transported via HTTP. + +### 2.2.3 EDC Data Asset Structure + +This API do not have to be accessed via an EDC instance but can be +queried from any authorized participant or service directly. + +### 2.2.4 Error Handling + +HTTP standard response codes that MUST be used. + +#### 2.2.4.1 Error Messages & Explanation + +| Code | Description | +|-------------|------------------------------------------------| +| 200 | Discovery request finished successfully | +| 400 | Request body was malformed | +| 401 | Not authorized | +| 403 | Forbidden | +| 405 | Method not allowed | + +## 3 REFERENCES + +### 3.1 Normative References + +Following Standards are used within this standard: + +- GAIA-X Trustframework: + https://gaia-x.eu/wp-content/uploads/2022/05/Gaia-X-Trust-Framework-22.04.pdf +- CX - 0006 Registration and initial onboarding +- CX - 0010 Business Partner Number + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0001-EDCDiscoveryAPI/assets/CX-0001-main-components.drawio b/docs/standards/CX-0001-EDCDiscoveryAPI/assets/CX-0001-main-components.drawio new file mode 100644 index 000000000..dc4da8c8a --- /dev/null +++ b/docs/standards/CX-0001-EDCDiscoveryAPI/assets/CX-0001-main-components.drawio @@ -0,0 +1,212 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/standards/CX-0001-EDCDiscoveryAPI/assets/CX-0001-main-components.png b/docs/standards/CX-0001-EDCDiscoveryAPI/assets/CX-0001-main-components.png new file mode 100644 index 000000000..f8b7029eb Binary files /dev/null and b/docs/standards/CX-0001-EDCDiscoveryAPI/assets/CX-0001-main-components.png differ diff --git a/docs/standards/CX-0002-DigitalTwinsInCatenaX/CX-0002-DigitalTwinsInCatenaX.md b/docs/standards/CX-0002-DigitalTwinsInCatenaX/CX-0002-DigitalTwinsInCatenaX.md new file mode 100644 index 000000000..0245a5d9d --- /dev/null +++ b/docs/standards/CX-0002-DigitalTwinsInCatenaX/CX-0002-DigitalTwinsInCatenaX.md @@ -0,0 +1,725 @@ +--- +position: 1 +--- + +# CX-0002 Digital Twins in Catena-X v2.2.0 + +## ABSTRACT + +The Catena-X network is about accessing/sharing/providing/using data, +formulated in the different use cases. This standardization +scenario is about how the data, and the data models look like and how the modelling has to be done, so that data between +ecosystem partners can be shared, lossless and in a machine-readable +way. This document focuses on Digital Twins and their application and +administration within Catena-X. + +The purpose of this standard is to provide concepts and +specifications in order to allow proper data provisioning with +Digital Twins in Catena-X. + +## FOR WHOM IS THE STANDARD DESIGNED + +This standard is designed as an implementable specification and thus +is relevant for all technical roles concerned with APIs and Data Exchange +in the Catena-X network + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +- Remove all normative references to the EDC implementation +- Declare outdated typization mechanism (asset:prop:type) optional + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +This standard is relevant for + +- data provider / consumer +- solution provider + +The standard is applicable in the following cases for the +following roles: + +- all data providers who need to provide information via Digital Twins +- all data consumers and business application provider who need access + to data provided via Digital Twins +- solution providers of a Digital Twin Registry +- onboarding service providers who need to offer core service of a + Digital Twin Registry to their customers +- enabling service providers who need access to data provided via Digital Twins +- consulting service providers who need to explain how Digital Twins are implemented and/or used + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +Catena-X creates a decentral, uniform, and consistent solution for data sharing +in automotive industry. In this context, the +exchange of data is an essential requirement for the +success of this network. For this purpose, Catena-X provides various +methods, tools, and standards to ensure semantic interoperability. +Digital Twins have established themselves here as a central element for +structuring and accessing data. With the help of defined semantics, both +data provisioning and app development are simplified and encouraged. + +#### 1.2.1 Digital Twins in Catena-X + +The term Digital Twin (DT) describes a digital representation of an asset sufficient +to meet the requirements of a set of use cases. + +Any asset - it can be an actual physical asset like an engine hood +but also something virtual like a web service - has a digital +representation with consistent semantics. Hence, Digital Twins adhere to +the following characteristics: + +- The DT has at least one Catena-X-wide unique identifier (ID). + +- An asset can have more than one DT. However, each DTR may only contain a single DT for each asset. + +- DTs organize a set of Aspects. A DT's set of aspects can be extended over lifetime. + +- An Aspect of a DT includes both structural and behavioral + data and models, including operations and simulation models. + +- The semantics of an Aspect can be described via semantic models. + +- A single Aspect can be connected to different heterogeneous data + sources, including behavioral models. + +- The DT can represent type assets (*e.g.*, virtual prototype of a car) + and instance assets (*e.g.*, real car). + +- A DT can cover the whole asset lifecycle including, *e.g.*, the + planning, production, sales, use, and decommissioning phases. + However, in practice there may be more than one twin with different + IDs representing different lifecycle phases, *e.g.*, one twin for types + and multiple twins for instances. + +- The DT represents current available information about an asset, + synchronized at a specified frequency and fidelity, which can be + leveraged for simulation and business process integration. + +- By using Aspects, a DT can reference other DTs to express \"part + of\" or \"consists of\" relations. + +- In the context of Catena-X Digital Twins are exposed to the Catena-X Dataspace according to the + Dataspace Protocol (DSP). + +#### 1.2.2 Digital Twin Registry + +A Digital Twin Registry (DTR) is an operated solution which lists Digital +Twins and their respective Aspects. Each Digital Twin represents a single asset. +Some basic information about the asset being represented is part of each entry in a DTR. + +For each asset, several data sets in form of Aspects can be provided. +These Aspects are referenced in each Digital Twin together with +information about access to the Aspect endpoints. + +Moreover, a DTR also offers basic discovery functionality to find +Digital Twin(s) representing an asset under consideration. + +In general, every data provider in the dataspace must decide how and where to operate a DTR. + +The data provider needs to register all their Digital Twins including its respective Aspects +to its DTR service in order to reveal its \"offer\" of sharing respective +data sets. + +The data offered by a Digital Twin via Aspects should be semantically described by a +semantic Aspect metamodel conformant to CX-0003. + +#### 1.2.3 Asset Administration Shell + +The Asset Administration Shell (AAS) is a key concept of Industry 4.0 +(or "Industrie 4.0" in German), maintained by the [Industrial Digital Twin +Association](https://industrialdigitaltwin.org) (IDTA), and is used to describe an asset +electronically in a standardized manner. The AAS is a standardized way to implement a Digital Twin. +One of the main concepts of the AAS is the concept of Submodels, each of which can characterize the +asset by describing its Aspects for different use cases and data consumers. + +The specifications of the AAS offers a set of standardized API methods and resources to access data of a Digital Twin. + +Also, an Asset Administration Shell Registry service and other services in the context of Digital +Twins are standardized. + +In Catena-X the semantics of a Submodel is described via an Aspect Model conformant to standard CX-0003, +preferrable by using standardized properties conformant to standard CX-0044. + +The following figure gives a high-level overview how the concepts relevant for this standard relate +with each other and concepts from neighboring domains. +![Terminology](./assets/CX-0002-picture2.png "Non-normative overview of relations between terms relevant +in CX - 0002") + +In general, the AAS has proven to be suitable for the following missions: + +- representing data exchanged in a standardized way between two parties (API payload) + +- Providing uniform access to data exchanged between two parties (API operations) + +- Data discovery for the asset under consideration for + exchange between two parties in a standardized way (Digital Twin Registry) + +The [Asset Administration Shell Reading Guide](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/2022-12-07_IDTA_AAS-Reading-Guide.pdf) +gives an overview for different stakeholders. +This reading guide together with detailed technical documentation can be found in the Content Hub of the IDTA and on GitHub: +[https://github.com/admin-shell-io/aas-specs](https://github.com/admin-shell-io/aas-specs). + +#### 1.2.4 Architecture Overview + +The Digital Twin Registry (DTR) component is a decentral component in the Catena-X dataspace. Typically, each data provider offers its own DTR, either using an enablement service provider that also operates the DTR for the data provider or operating it themselves. + +The DTR does not only contain pure registration functionality but also basic +discovery functionality based on asset identifiers. The corresponding APIs for this kind of discovery are +specified in this document. + +A DTR is accessed via a dataspace connector conformant to standard CX-0018. Business solutions first need to find the relevant connectors and thus negotiate with them for the relevant DTR. Additionally to EDC Discovery (see standard CX-0001), additional discovery services (see standard CX-0053) are provided to reduce the number of dataspace connectors that need to be accessed by the business application. + +![TwinArch](./assets/CX-0002-picture1.jpg "Pattern for decentralized Digital Twin Registry") + +### 1.3 CONFORMANCE + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, +diagrams, examples, and notes in this specification are non-normative. +Everything else in this specification is normative. + +The keywords MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, +SHOULD and SHOULD NOT in this document are to be interpreted as described in \[[BCP +14](https://datatracker.ietf.org/doc/html/bcp14)], \[[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)\], +\[[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)\] when, and +only when, they appear in all capitals, as shown here. + +### 1.4 PROOF OF CONFORMITY + +All participants and their solutions will need to prove that they +conform to the Catena-X standards. To validate that the standards are +applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +#### 1.4.1 Proof of Conformity for Digital Twin Registry Solutions + +A Digital Twin Registry solution MUST provide http/REST APIs conformant +to the openAPI specifications adopted in this document. + +In case the Digital Twin Registry solution already has a valid certificate of the +[Industrial Digital Twin Association](https://industrialdigitaltwin.org) (IDTA) including the +required service specification profiles the simplified certification process of Catena-X e.V. holds. + +If there is no valid certificate available from the IDTA, Digital Twin Registry solution providers +MUST prove their conformity by providing: + +- An openAPI specification of the implemented endpoints. +- Documentation that the implementation's API responses match to the response structure of the required API specifications in this document. + +A Digital Twin Registry Solution MUST include mechanisms that allow to ensure confidentiality and integrity of data, and compliance with antitrust laws. + +On default, the read access to Digital Twins SHOULD be enabled by Digital Twin Registry Solutions to data providers only. + +#### 1.4.2 Proof of Conformity for Data Providers + +A data provider MUST offer the http/REST APIs for its Digital Twin Registry service conformant to +this specification. + +In case the Digital Twin Registry solution already has a valid certificate of the +[Industrial Digital Twin Association](https://industrialdigitaltwin.org) (IDTA) including the +required service specification profiles the simplified certification process of Catena-X e.V. holds. + +The Digital Twin Registry service used by the data provider MUST be registered in the dataspace connector selected +by the data provider. + +A data provider MAY create and register Digital Twins using the +http/REST APIs conformant to the openAPI specification as defined in +this document. + +The data provider MUST offer the READ operations for Digital Twins and its Aspects conformant to +this specification. + +The endpoints offered by the data provider MUST be made accessible to the dataspace +as specified in this document or other use case related standards. + +Appropriate usage policies conformant to standard CX-0018 and subsequent use-case-standards MUST be defined for accessing the Digital Twin Registry itself as well as for the Submodels. + +Data providers MUST comply with antitrust law, *i.e.*, competitively sensitive information (*e.g.* customer names, supplier names, prices, price models, internal knowhow, sales and/or purchasing strategies) MUST NOT be published via a DTR. + +The data provider SHOULD use the unique identifier of the standardized Aspect Model conformant to CX-0003 when registering a new Submodel endpoint to a DTR. + +A data provider SHOULD add specific asset IDs for each Digital Twin to enable discovery. +Other CX-standards may make more specific demands for Data Providers which specific assetIDs are to be added. + +A data provider SHOULD add information to available discovery services conformant to standard CX-0001 and +CX-0053 - if available - to enable data consumers to find the relevant DSP-endpoints and thus the Digital Twin Registry +the data consumer is interested in. + +#### 1.4.3 Proof of Conformity for Data Consumers + +A data consumer, business application provider or enabling service +provider MAY lookup the endpoints of the Submodels relevant for the use +case using the http/REST APIs conformant to the openAPI specification as +defined in this document. + +Since there are several Digital Twin Registries in the dataspace data +consumers, business application providers or enabling service providers +MAY first lookup the available Digital Twin Registry endpoints of the +relevant dataspace connectors using the corresponding standardized EDC discovery services (see standard CX-0001). + +Additionally, data consumers MAY use standardized discovery services - +if available -, *e.g.*, to find a relevant dataspace connector for a specific company via its +BPN (see standard CX-0053). + +### 1.5 Examples + +Examples can be found in +[the Tractus-X DTR's documentation](https://github.com/eclipse-tractusx/sldt-digital-twin-registry/tree/main/docs) and the [Digital Twin Kit](https://eclipse-tractusx.github.io/docs-kits/next/category/digital-twin-kit/) + +### 1.6 Terminology + +> *This section is non-normative* + +#### Aspect + +> a domain-specific view on information and functionality associated with +a specific *[Digital Twin](#digital-twin)* with a reference to a concrete *[Aspect Model](#aspect-model)*. + +Note 1 to entry: An Aspect is a software service to retrieve the actual +runtime data of a Digital Twin (current or aggregated) from a data +source or to trigger operations. Thus, an Aspect is built with an +implementation that ensures that the exchanged data is compliant to the +specification of the referenced Aspect Model via a defined +interface. + +Note 2 to entry: Aspects are registered (incl. their "API endpoint" +information) within the Digital Twin to which they belong in the +Digital Twin Registry. + +Note 3 to entry: an Aspect corresponds to a *[Submodel](#submodel)* in the *[Asset Administration Shell](#asset-administration-shell)* + +*\[SOURCE: [Eclipse Semantic Modeling Framework (ESMF)](https://projects.eclipse.org/projects/dt.esmf), editorial changes and notes +added\]* + +#### Aspect Model + +> a formal, machine-readable semantic description (expressed with +RDF/turtle) of data accessible from an *[Aspect](#aspect)*. + +Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta +Model (SAMM), *i.e.*, it utilizes elements and relations defined in the +SAMM and is compliant with the validity rules +defined by the SAMM. + +Note 2 to entry: Aspect Models are logical data models which can be used +to detail a conceptual model in order to describe the semantics of +runtime data related to a concept. Further, elements of an Aspect Model +can/should refer to terms of a standardized Business Glossary (if +existing). + +Note 3 to entry: An Aspect Model may describe the semantics of a *[Submodel](#submodel)*. + +\[SOURCE: [Eclipse Semantic Modeling Framework (ESMF)](https://projects.eclipse.org/projects/dt.esmf), editorial changes and notes added\] + +#### Asset Administration Shell + +> standardized *[digital representation](#digital-representation)* of an asset + +Note 1 to entry: Asset Administration Shell and Administration Shell are +used synonymously. + +\[SOURCE: IEC 63278-1, note added\] + +#### Digital Twin + +> *[digital representation](#digital-representation)*, sufficient to meet the requirements of a set of +use cases + +Note 1 to entry: in this context, the entity in the definition of +digital representation is typically an asset. + +*\[SOURCE: IIC Vocabulary IIC:IIVOC:V2.3:20201025, adapted (an asset, +process, or system was changed to an asset)\]* + +#### Digital Representation + +> information and services representing an entity from a given + +EXAMPLE 1: examples of information are properties (*e.g.*, maximum +temperature), actual parameters (*e.g.*, actual velocity), events (*e.g.*, +notification of status change), schematics (electrical), and +visualization information (2D and 3D drawings). + +EXAMPLE 2: examples of services are providing the history of the +configuration data, providing the actual velocity, and providing a +simulation. + +EXAMPLE 3: examples of viewpoints are mechanical, electrical, or +commercial characteristics. + +\[SOURCE: IEC 63278-1, editorial changes\] + +#### Submodel + +> container of *[SubmodelElements](#submodel-element)* defining a hierarchical structure +consisting of SubmodelElements + +\[SOURCE: IEC 63278-1\] + +#### Submodel Element + +> elements in a *[Submodel](#submodel)* + +\[SOURCE: IEC 63278-1\] + +## 2. Digital Twin Registry API for Solution Providers \[NORMATIVE\] + +### 2.1 API Specification + +#### 2.1.1 Standards and Profiles + +The specification +*[Specification of the Asset Administration Shell - Part 2: Application Programming Interfaces](#61-normative-references)* +is the basis for the Digital Twin Registry implementation in Catena-X. +The document can be found in the content hub of IDTA: [https://industrialdigitaltwin.org/content-hub](https://industrialdigitaltwin.org/content-hub). + +The API is offered as OpenAPI file in addition to its formal specification published on [https://industrialdigitaltwin.org/](https://industrialdigitaltwin.org/). + +For relevant profiles of the Service Specifications see chapters on *[API endpoints & resources](#212-api-endpoints--resources)*. + +#### 2.1.2 API Endpoints & resources + +The API MUST be implemented as specified for the profiles: + +- *[Asset Administration Shell Registry Service Specification V3.0 READ Profile SSP-002](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.0_SSP-002)* + +- *[Discovery Service Specification V3.0 Profile SSP-001](https://app.swaggerhub.com/apis/Plattform_i40/DiscoveryServiceSpecification/V3.0_SSP-001)* + +The following profile SHOULD be implemented: + +- *[Asset Administration Shell Registry Service Specification V3.0 Profile SSP-001](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.0_SSP-001)* + +The following deviations are defined: + +- Length of *ProtocolInformation/subprotocolBody* string MUST be 2048 +- DELETE and POST operations of Discovery Interface are optional to be implemented +- *GetAllAssetAdministrationShellIdsByAssetLink* (`GET /lookup/shells`) is deprecated and will be succeeded in future releases. + +EXAMPLE for Self-Description (**GetSelfDescription**) of a Digital Twin Registry solution : + +````json +{ + "profiles": [ + "https://admin-shell.io/aas/API/3/0/DiscoveryServiceSpecification/SSP-001", + "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-002" + ] +} +```` + +API paths SHOULD be versioned only holding the major version of the AAS specification, for instance `/v3/`. + +> Note: However, the version segment of the API-endpoint will usually be hidden by a Proxy (for example an EDC Data Plane) that +obfuscates the base-URL while allowing restricted client-side navigation along the path-structure defined by the AAS +specification. For instance, a consumer can assume that (when accessing a DTR) adding the path-elements +`/shell-descriptors/{{someAasId}}` will reliably yield a response containing an AAS-Descriptor. + +#### 2.1.3 Available Data Types + +The API MUST use JSON as the payload transported via HTTP. + +For explanation of data types see *[Specification of the Asset Administration Shell - Part 2: +Application Programming Interfaces](#61-normative-references)*. + +#### 2.1.4 Representation in DSP catalogs + +Not applicable, since catalogs are created by data provider not by the DTR's solution provider. + +#### 2.1.5 Error Handling + +Error response **501 Not Implemented** MUST be used for operations or parameter values +not yet supported. + +For other error codes and error handling see *[Specification of the Asset Administration Shell - +Part 2: Application Programming Interfaces](#61-normative-references)*. + +## 3. Digital Twin Registry API for Data Providers \[NORMATIVE\] + +### 3.1 API Specification + +#### 3.1.1 Standards and Profiles + +The specification of the [Asset Administration Shell - Part 2: +Application Programming Interfaces](#61-normative-references) is the basis for the Digital Twin Registry +implementation in Catena-X. + +The API is offered as OpenAPI file in addition to its formal specification published on [https://industrialdigitaltwin.org/](https://industrialdigitaltwin.org/). + +For relevant profiles of the Service Specifications see chapters on *[API endpoints & resources](#312-api-endpoints--resources)*. + +#### 3.1.2 API Endpoints & resources + +The API MUST be implemented as specified for the profiles: + +- [Asset Administration Shell Registry Service V3.0 READ Profile SSP-002](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.0_SSP-002) + +- [Discovery Service Specification V3.0 Profile SSP-001](https://app.swaggerhub.com/apis/Plattform_i40/DiscoveryServiceSpecification/V3.0_SSP-001) + +The WRITE operations of the following profile MAY be used to create and delete Digital Twins: + +- [Asset Administration Shell Registry Service Profile V3.0 Profile SSP-001](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.0_SSP-001) + +The same deviations are defined as for Digital Twin solution providers. + +API paths SHOULD be versioned only holding the major version of the AAS specification, for instance `/v3/`. + +> Note: However, the version segment of the API-endpoint will usually be hidden by a Proxy (for example an EDC Data Plane) that obfuscates the base-URL while allowing restricted client-side navigation along the path-structure defined by the AAS specification. For instance, a consumer can assume that (when accessing a DTR) adding the path-elements `/shell-descriptors/{{someAasId}}` will reliably yield a response containing an AAS-Descriptor. + +#### 3.1.3 Available Data Types + +The API MUST use JSON as payload transported via HTTP. + +For explanation of data types see [Specification of the Asset Administration Shell - Part 2: +Application Programming Interfaces](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API.pdf). + +#### 3.1.4 Representation in DSP catalogs + +A Digital Twin Registry that is made accessible via a DSP-compliant connector MUST expose the [`dcat:Dataset`](https://www.w3.org/TR/vocab-dcat-2/#Class:Dataset) representing the DTR to be registered with the following properties and restrictions on their values. + +- `"dct:type": {"@id":"https://w3id.org/catenax/taxonomy#DigitalTwinRegistry"}`. The "dct" prefix MUST resolve to "http://purl.org/dc/terms/". +- `"cx-common:version"`. The "cx-common" prefix MUST resolve to "https://w3id.org/catenax/ontology/common#". The value MUST indicate the major and minor version of the implemented AAS-specification and must be at least `"3.0"`. For more details on conventions in `dcat:Catalogs`, see CX-0018. + +For backward compatibility it MAY be necessary to still provide the deprecated `"asset:prop:type": "data.core.digitalTwinRegistry"` entry. + +As the Digital Twin Registry is an Enablement Service that is shared across use-cases, it SHOULD be offered via a set +of policies agnostic to the FrameworkCredentials of a participant. + +#### 3.1.5 Error Handling + +Error response **501 Not Implemented** MUST be used for operations or parameter values +not yet supported. + +For other error codes and error handling see *[Specification of the Asset Administration Shell - +Part 2: Application Programming Interfaces](#61-normative-references)*. + +## 4. Submodel API for Data Providers \[NORMATIVE\] + +### 4.1 API Specification + +#### 4.1.1 Standards and Profiles + +The [Specification of the Asset Administration Shell - Part 2: +Application Programming Interfaces](#61-normative-references) +is the basis for exchanging data via Digital Twins in Catena-X. + +The API is offered as OpenAPI file in addition to its formal specification published on [https://industrialdigitaltwin.org/](https://industrialdigitaltwin.org/). + +For relevant profiles of the Service Specifications see chapters on *[API endpoints & resources](#412-api-endpoints--resources)*. + +API paths SHOULD be versioned only holding the major version of the AAS specification, for instance `/v3/`. + +> Note: However, the version segment of the API-endpoint will usually be hidden by a Proxy (for example an EDC Data Plane) that obfuscates the base-URL while allowing restricted client-side navigation along the path-structure defined by the AAS specification. For instance, a consumer can assume that when accessing data from a single registered Submodel, adding the path-element `$value` will reliably yield a response containing the value-only serialization of a Submodel. + +#### 4.1.2 API Endpoints & resources + +A Submodel that provides data MUST be implemented in conformance to the API-definition of +[Submodel Service Specification V3.0 VALUE ONLY Profile SSP-003](https://app.swaggerhub.com/apis/Plattform_i40/SubmodelServiceSpecification/V3.0_SSP-003) +of the Submodel Service Specification. + +--- + +**NOTE** +The logical operation *GetSubmodel* can be implemented in different ways. The only relevant +information for the data consumer is the endpoint information in the Digital Twin Registry. +Besides its availability in the Submodel Service Specification the *GetSubmodelById* operation is +functionally equivalent if the full path is given. It is available in +the Asset Administration Shell Service Specification as well as the Submodel Repository Service +Specification or Asset Administration Shell Repository Service Specification via superpaths. + +--- + +The following additional restrictions apply: + +- The `semanticId` of a referred Submodel MUST also be added to the Submodel Descriptor registered for the DT (*SubmodelDescriptor/semanticId*). + - A data provider MUST use the unique identifier of the Aspect Model standardized in Catena-X conformant to standard CX-0003 when registering + a corresponding new Aspect to a Digital Twin (*Submodel/semanticId*). +- The `subprotocol` MUST be set to "DSP" (*SubmodelDescriptor/endpoints/protocolInformation/subprotocol*). +- The `subprotocolBody` must be set according to the concatenation of the following key-value-pairs (assigned by a "=" and separated by a semicolon ";"): + - `id` represents the id of that dcat:DataSet in the Data Providers catalog that contains the Submodel. + - `dspEndpoint` represents the endpoint of the Data Provider's Control Plane where the catalog containing the relevant dcat:DataSet is located. +- The `href` property (*SubmodelDescriptor/endpoints/protocolInformation/href*) MUST be set to the concatenation of the relevant Data Plane endpoint concatenated with the relative path to the resource's endpoint that exposes the logical operation `GetSubmodel` or `GetSubmodelById`, respectively. A Data Consumer is allowed to attempt swapping the Data Plane endpoint if the Data Provider has signalled that it differs from the `href`. This may be signalled via the access token returned from the transfer process. + +A full example satisfying these restrictions is at the end of this chapter. + +Beside Aspect Models standardized in Catena-X also other Aspects may be registered, either +conformant to proprietary standards or standards from other organizations. +However, these Aspects are not fit to be used in Catena-X use cases or standards. +In either case, an Aspect Model conformant to standard CX-0003 SHOULD be made available for these Aspects. + +The following deviations are allowed, *i.e.*, the following API operations and operation parameters +SHOULD be supported but these are not mandatory to be implemented. + +- provision of API **/description** +- support of API operation **/submodel** (*i.e.*, logical interface operation "GetSubmodel with + logical parameter "Content"="Normal", the API operation **/submodel/$value** extending the + default operation's URL with the parameter **/submodel/$value** remains mandatory) +- support of API operation **/submodel/submodel-elements/< IdShortPath >/invoke** and + **/submodel/submodel-elements/< IdShortPath > /invoke/$value** +- support of query parameter **Extent=WithoutBLOBValue** + +--- + +**NOTE** +for Profile SSP-003 of the Submodel Service Specification the following parameters are not included: + +- no provision of API **/serialization** +- no support of logical parameter **Content=Metadata**, *i.e.*, no support of API operation with path + parameter "$metamodel" **/submodel$metamodel** +- no support of logical parameter **Content=Reference**, *i.e.*, no support of API operation with + path parameter "$reference" **/submodel/$reference** +- no support of logical parameter **Content=Path**, *i.e.*, no support of API operation with path + parameter "$path" **/submodel/$path** +- no support of query parameter **Level=Core** (only of **Level=Deep**) + +--- + +EXAMPLE for a Submodel descriptor in the DTR accessible via a DSP-compliant connector, separated in control plane and +Data Plane: + +```json +{ + "id": "", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:bamm:io.catenax.material_for_recycling:1.1.0#MaterialForRecycling" + } + ] + }, + "endpoints": [ + { + "protocolInformation": { + "href": "https://edc.data.plane//submodel", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id=123;dspEndpoint=https://edc.control.plane/", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + }, + "interface": "SUBMODEL-3.0" + } + ] +} + +``` + +The endpoint within the SubmodelDescriptor MUST not contain the path suffix for the logical parameter "Content" like in */submodel/$value*. The data consumer will add the needed path suffix explicitly to the endpoint before calling the value-only Submodel operation. + +#### 4.1.3 Available Data Types + +The API MUST use JSON as payload transported via HTTP. + +#### 4.1.4 Representation in DSP catalogs + +Access to the Submodels of a Digital Twin MUST take into account restrictions set by policies defined for them at the +connector to the Dataspace (see standard CX-0018). + +The data provider MAY cluster several Submodels into one `dcat:Dataset`. + +If a single Submodel is registered as a single `dcat:Dataset`, its MUST be registered with the following restrictions on +values for given properties. + +- `"dct:type": {"@id":"https://w3id.org/catenax/taxonomy#Submodel"}`. The "dct" prefix MUST resolve to "http://purl.org/dc/terms/". +- `"cx-common:version"`. The "cx-common" prefix MUST resolve to "https://w3id.org/catenax/ontology/common#". The value +MUST indicate the major and minor version of the implemented AAS-specification and must be at least `"3.0"`. + +In that case, Data Providers SHOULD also add a property `aas-semantics:semanticId` that is set to the composite semanticId of the Submodel that the Asset represents. The "aas-semantics" prefix MUST resolve to "https://admin-shell.io/aas/3/0/HasSemantics/". + +For more details on conventions in `dcat:Catalog`s, see CX-0018. + +#### 4.1.5 Error Handling + +Error response **501 Not Implemented** MUST be used for API operations and parameter values +not yet supported. + +For error handling see +[Specification of the Asset Administration Shell - Part 2: Application Programming Interfaces](#61-normative-references). + +## 5. Submodel API for Data Consumers \[NORMATIVE\] + +The specification +[Specification of the Asset Administration Shell - Part 2: Application Programming Interfaces](#61-normative-references) +is the basis for consuming data via Digital Twins in Catena-X. + +The API is offered as OpenAPI file in addition to its formal specification published on [https://industrialdigitaltwin.org/](https://industrialdigitaltwin.org/). + +This is the relevant service specification profile for data consumers: + +- [Submodel Service Specification V3.0 READ Profile SSP-003](https://app.swaggerhub.com/apis/Plattform_i40/SubmodelServiceSpecification/V3.0_SSP-003) + +The READ API operations of the Asset Administration Shell profile SSP-003 of the Submodel Service +Specification MAY be used to access the Submodels provided by data providers. + +The logical parameter "Content" is realized via path suffixes (starting with `$`) like in `/submodel/$value`. The endpoint within the Digital Twin Registry is not including the path suffixes. This is why the path suffix needs to be explicitly added to the endpoint before calling the value-only Submodel operation, ensuring type-safety for the response object. A logical parameter like "Level" is realized as query parameter. + +--- + +**NOTE** +The logical *GetSubmodel* operation is not called explicitly by the data consumer. Instead, the +endpoint as provided via the Digital Twin Registry for the asset and *Submodel* of interest is +called with GET. +Additionally, the data consumer MAY need to set parameters before calling the API operation. + +--- + +## 6. References + +### 6.1 Normative References + +- Specification of the Asset Administration Shell - Part 1: Metamodel. V3.0, April + 2023, IDTA number: 01001-3-0 On [IDTA Content Hub](https://industrialdigitaltwin.org/content-hub) + +- Specification of the Asset Administration Shell - Part 2: Application Programming + Interfaces. V3.0, April 2023, IDTA number: 01002-03-1 On [IDTA Content Hub](https://industrialdigitaltwin.org/content-hub) + +### 6.2 Non-Normative References + +> *This section is non-normative* + +- [Asset Administration Shell Reading Guide](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/2022-12-07_IDTA_AAS-Reading-Guide.pdf) + +- CX-0003 SEMANTIC ASPECT META MODEL v1.1.0. In [Catena-X Standard Library](https://catena-x.net/de/standard-library) +- CX-0018 DATASPACE CONNECTIVITY v3.0.0. In [Catena-X Standard Library](https://catena-x.net/de/standard-library) +- CX-0001 EDC DISCOVERY API v1.0.2. In [Catena-X Standard Library](https://catena-x.net/de/standard-library) +- CX-0053 BPN Discovery Service APIs v1.0.1. In [Catena-X Standard Library](https://catena-x.net/de/standard-library) +- CX-0044 ECLASS v1.0.2. In [Catena-X Standard Library](https://catena-x.net/de/standard-library) + +### 6.3 Reference Implementations + +> *This section is non-normative* + +The following open-source project implements a Digital Twin Registry +solution conformant to this standard: + +[https://github.com/eclipse-tractusx/sldt-digital-twin-registry](https://github.com/eclipse-tractusx/sldt-digital-twin-registry) + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +Terminology - "Non-normative overview of relations between terms relevant +in CX - 0002" + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0002-DigitalTwinsInCatenaX/assets/CX-0002-picture1.jpg b/docs/standards/CX-0002-DigitalTwinsInCatenaX/assets/CX-0002-picture1.jpg new file mode 100644 index 000000000..d79cb5cea Binary files /dev/null and b/docs/standards/CX-0002-DigitalTwinsInCatenaX/assets/CX-0002-picture1.jpg differ diff --git a/docs/standards/CX-0002-DigitalTwinsInCatenaX/assets/CX-0002-picture2.png b/docs/standards/CX-0002-DigitalTwinsInCatenaX/assets/CX-0002-picture2.png new file mode 100644 index 000000000..0b72d23d1 Binary files /dev/null and b/docs/standards/CX-0002-DigitalTwinsInCatenaX/assets/CX-0002-picture2.png differ diff --git a/docs/standards/CX-0003-SAMMSemanticAspectMetaModel/CX-0003-SAMMSemanticAspectMetaModel.md b/docs/standards/CX-0003-SAMMSemanticAspectMetaModel/CX-0003-SAMMSemanticAspectMetaModel.md new file mode 100644 index 000000000..77486f9b3 --- /dev/null +++ b/docs/standards/CX-0003-SAMMSemanticAspectMetaModel/CX-0003-SAMMSemanticAspectMetaModel.md @@ -0,0 +1,365 @@ +--- +category: test +--- + +# CX-0003 SAMM Aspect Meta Model v1.1.0 + +## ABSTRACT + +The [Semantic Aspect Meta Model (SAMM)](https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model), an open standard, shall be used for +defining the semantics of the different aspects of an asset that is +represented via a digital twin. Aspect models are machine readable and +other artifacts can be derived from it. The aspect model is the common +basis for the http/REST API for accessing data via the standardized +digital twin API of the Asset Administration Shell. + +## FOR WHOM IS THE STANDARD DESIGNED + +This standard is designed for semantic modelling and usage of semantic models in Catena-X. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +Changes compared to V1.0.2 of CX-0003: + +- Update to SAMM V2.1.0 +- No acceptance of deprecated BAMM aspect models any longer +- Update to new version of operating model +- Update to conform to new standard document structure + +## 1 Introduction + +### 1.2 Audience & Scope + +*This section is non-normative* + +This standard is relevant for the following roles: + +- Business Application Provider +- Data Provider / Consumer +- Core Service Provider +- Enablement Service Provider +- Onboarding Service Provider +- Consulting Service Provider + +The standard needs to be applied in the following cases for the +following roles: + +- Business Application Providers who want to request or create proprietary new aspect models +- Data Providers who need to create digital twins offering data conformant to a specific aspect model and want to understand the underlying metamodel +- Data Consumers who need to understand the data offered by a digital twin and want to understand the underlying metamodel of the corresponding aspect model +- Core, enablement and onboarding service providers who offer services in the context of the Semantic Hub or for tooling based on aspect models +- Consulting service providers who offer consulting for data consumers and data providers + +### 1.2 Context and Architecture Fit + +*This section is non-normative* + +#### Context + +In Catena-X, along with [GAIA-X](ttps://gaia-x.eu/), Digital Twins are to be considered as a core concept to exchange data in the data space. + +The Digital Twin Architecture Pattern focuses on ensuring (semantic) interoperability via Digital Twins and Semantic Models in a federated system. + +A Digital Twin System forms the basis for comprehensive digitization of production and logistics by gradually creating consistent data homogeneity and interoperability. Since not everyone needs the same set of information, a Digital Twin is a collection of various aspects of an asset. An aspect can, for example, bundle all information about machine malfunctions. Such aspects are characterized by concrete aspect models that describe formally how an aspect is structured. Aspect models describe things like the units of measurement and possible value range for a temperature sensor in a way that is readable by machines. This allows for faster, more automated responses to the data as it is +received. Here, a meta model is a model that defines the constructs and properties used by aspect models. Expressing this aspect's semantics to consumers of the data can open up completely new possibilities. In other words, an aspect meta model provides the machine-readable language or +semantics used across an entire system of aspect models. Hence, the [Semantic Aspect Meta Model (SAMM)](https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model) allows the creation of meta models to describe the semantics of digital twins by defining their domain-specific aspects, containing information about both the runtime data structure (e.g., that there is a property in the data called "temperature", and that it has a numeric value) and information that is not part of the runtime data (e.g., the unit or range). It does not, however, contain actual runtime data (e.g., a numeric value representing the current temperature), as this will be delivered by an Aspect +conforming to this Aspect model. The combination of raw runtime data and its corresponding Aspect model yields information. Moreover, the SAMM allows to reuse semantic descriptions across different aspect models. + +#### Architecture Overview + +This chapter just gives a rough overview of the architecture. + +The architectural component "Semantic Hub" is considered to be a core service. The architectural component "Digital Twin Registry" is considered to be an enabling service. "The Enablement Services are a bundle of decentral services that enable participation in the Catena-X data space. Each participant must deploy and use the enablement services to connect to the data space and enable standardized interactions based on the requirements of the respective use case." For more details see [Catena-X Operating Model Whitepaper](https://catena-x.net/fileadmin/user_upload/Publikationen_und_WhitePaper_des_Vereins/CX_Operating_Modelv2.1_final.pdf). + +The Semantic Hub is a database containing aspect models released in Catena-X. These aspect models are accessible via a UI in the Catena-X Portal. The database is synchronized with the public github (see [Proof of conformity](#13-conformance-and-proof-of-conformity)) containing the machine-readable specification of the aspect models that shall be conformant to the Semantic Aspect Meta Model as specified in this document. Every aspect model has a unique ID and this is why it can be referenced. Up to now there is a central Semantic Hub for the complete data space. This makes sense for the standardized and released aspect models. In the future also proprietary aspect models might be defined. So also decentralized Semantic Hubs will be possible. + +A Digital Twin Registry contains the digital twins of a data provider +together with access information for the single aspects associated with +a digital twin. Additionally, every aspect of a digital twin contains +information about its semantics. The semantics is described via an +aspect model conformant to the Semantic Aspect Meta Model as specified +in this document. + +The Eclipse Data Space Connector (EDC) (see standard [CX-0018](https://catena-x.net/de/tractus-x/standard-library)) defines access and usage policies for the different digital twins and aspects of the digital twins. + +### 1.3 Conformance and Proof of Conformity + +#### Conformance + +As well as sections marked as non-normative, all authoring guidelines, +diagrams, examples, and notes in this specification are non-normative. +Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD and SHOULD NOT in this document are to be interpreted as described in \[[BCP 14](https://datatracker.ietf.org/doc/html/bcp14)], \[[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)\], \[[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)\] when, and only when, they appear in all capitals, as shown here. + +#### Proof of Conformity + +*This section is non-normative* + +All participants and their solutions will need to prove that they conform to the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +Every aspect model released or standardized in Catena-X MUST be +maintained in [Tractus-X - SLDT Semantic Models](https://github.com/eclipse-tractusx/sldt-semantic-models). + +For [validation of aspect models](https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/java-aspect-tooling.html#validating-aspect-models) open-source tool support is available as part of the [ESMF SDK](https://github.com/eclipse-esmf/esmf-sdk). + +Every aspect model in +[Tractus-X - SLDT Semantic Models](https://github.com/eclipse-tractusx/sldt-semantic-models) that has the +status "released" or "standardized" MUST be validated without errors +against the Semantic Aspect Meta Model. For the current version of the +Semantic Aspect Meta Model under consideration see [normative references](#31-normative-references). +For the currently used version of the Validator see information in +[Readme](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/README.md). +Newer versions of the validator can be used but need an explicit +decision and -- if needed -- a migration path of all existing and +released aspect models to do so. + +The governance process for new, updated or deprecated aspect models is defined by Catena-X e.V. Additionally, the [governance process](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/documentation/GOVERNANCE.md) is described in the github project. + +Every aspect of a digital twin registered in a digital twin registry (see standard [CX-0002](CX-0002-DigitalTwinsInCatenaX)) accessible in the Catena-X data space MUST have a semantic description (semantic ID) that is conformant to the unique identifier of the SAMM aspect model associated to it. + +### 1.4 Examples + +An example would be an aspect models to exchange information about the +carbon footprint (PCF) of a product. This aspect model would specify +that the following information is mandatory to be transferred: the +footprint itself but also the product footprint identifier, the product +footprint specification version and the product category. Optionally +also land use emissions may be provided. + +An extract from a corresponding machine-readable specification of the +aspect model conformant to the Semantic Aspect Meta Model could look +like this: + +``` +:ProductFootprintVersionCharacteristic a samm:Characteristic; + + samm:name "ProductFootprintVersionCharacteristic"; + + samm:preferredName "Product Footprint Version Characteristic"@en; + + samm:description "Characteristic for defining a product footprint version as specified by the WBCSD (World Business Council for Sustainable Development) Pathfinder initiative."@en; + + samm:see https://wbcsd.github.io/introduction/; + + samm:dataType xsd:positiveInteger. +``` + +For more examples of aspect models conformant to the Semantic Aspect Meta Model see https://github.com/eclipse-tractusx/sldt-semantic-models. + +### 1.5 Terminology + +*This section is non-normative* + +#### Aspect + +> a domain-specific view on information and functionality associated with +a specific [*Digital Twin*](#digital-twin) with a reference to a concrete [*Aspect Model*](#aspect-model). + +Note 1 to entry: An Aspect is a software service to retrieve the actual +runtime data of a Digital Twin (current or aggregated) from a data +source or to trigger operations. Thus, an aspect is built with an +implementation that ensures that the exchanged data is compliant to the +specification of the referenced Aspect Model via a defined +interface. + +Note 2 to entry: Aspects are registered (incl. their "API endpoint" +information) with the Digital Twin to which they belong in the +Digital Twin Registry. + +Note 3 to entry: an aspect corresponds to a [*Submodel*](#submodel) in the [*Asset Administration Shell*](#asset-administration-shell) + +*\[SOURCE: [Eclipse Semantic Modeling Framework (ESMF)](https://projects.eclipse.org/projects/dt.esmf](https://eclipse-esmf.github.io/samm-specification/snapshot/index.html), editorial changes and notes added \]* + +#### Aspect Model + +> a formal, machine-readable semantic description (expressed with +RDF/turtle) of data accessible from an [*Aspect*](#aspect). + +Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant with the validity rules defined by the Semantic Aspect Meta Model. + +Note 2 to entry: Aspect models are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +Note 3 to entry: An Aspect Model describes the semantics of a [*Submodel*](#submodel). + +*\[SOURCE: [Eclipse Semantic Modeling Framework (ESMF)](https://projects.eclipse.org/projects/dt.esmf](https://eclipse-esmf.github.io/samm-specification/snapshot/index.html), editorial changes and notes added \]* + +#### Asset Administration Shell + +> standardized [*digital representation*](#digital-representation) of an asset + +Note 1 to entry: Asset Administration Shell and Administration Shell are +used synonymously. + +*\[SOURCE: IEC 63278-1, note added\]* + +#### Submodel Template + +> guides the creation of a [*Submodel*](#submodel) conformant +to the [*Aspect Model*](#aspect-model) and the [*Asset Administration Shell*](#asset-administration-shell). + +*\[SOURCE: IEC 63278-1, extracted from text plus correlation with aspect model added \]* + +#### Digital Twin + +> [*digital representation*](#digital-representation), sufficient to meet the requirements of a set of use cases + +Note 1 to entry: in this context, the entity in the definition of +digital representation is typically an asset. + +*\[SOURCE: IIC Vocabulary IIC:IIVOC:V2.3:20201025, adapted (an asset, +process, or system was changed to an asset)\]* + +#### Digital representation + +> information and services representing an entity from a given viewpoint + +EXAMPLE 1: examples of information are properties (e.g., maximum +temperature), actual parameters (e.g., actual velocity), events (e.g., +notification of status change), schematics (electrical), and +visualization information (2D and 3D drawings). + +EXAMPLE 2: examples of services are providing the history of the +configuration data, providing the actual velocity, and providing a +simulation. + +EXAMPLE 3: examples of viewpoints are mechanical, electrical, or +commercial characteristics. + +*\[SOURCE: IEC 63278-1, editorial changes\]* + +#### Submodel + +> container of [*SubmodelElement*](#submodelelement)s defining a hierarchical structure +consisting of SubmodelElements + +*\[SOURCE: IEC 63278-1\]* + +#### SubmodelElement + +> elements in a [*Submodel*](#submodel) + +*\[SOURCE: IEC 63278-1\]* + +#### Submodel template + +> container of Submodel template elements defining a hierarchical +structure consisting of Submodel template elements + +*\[SOURCE: IEC 63278-1, note removed\]* + +Additional terminology used in this standard can be looked up in the +glossary on the association homepage. + +## 2 Semantic Aspect Meta Model (SAMM) + +### 2.1 Eclipse Semantic Modeling Framework + +The [Semantic Aspect Meta Model (SAMM)](https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model) is specified as an open standard +as integral part of the [Eclipse Semantic Modeling Framework (ESMF)](https://projects.eclipse.org/projects/dt.esmf). +This part again is part of the Top-Level Project [Eclipse Digital +Twin](ttps://projects.eclipse.org/projects/dt). The Eclipse Digital Twin Top-Level Project is a +collaborative, open-source initiative at the Eclipse Foundation +fostering the development of reference implementations for the +activities driven by the [Industrial Digital Twin +Association](https://industrialdigitaltwin.org) (IDTA). + +The core of the Eclipse Semantic Modeling Framework is the development +of the Semantic Aspect Meta Model (SAMM). Besides the SAMM specifying +the language to define the semantics of a submodel in an ["Aspect +Model"](#aspect-model), the ESMF also includes an editor, SDKs in different programming +languages, a command line tool for validation, generating documentation +and different serializations and other functionality easing its usage +and implementation in digital twin projects. Also, aasx generators for +support of ["Asset Administration Shell"](#asset-administration-shell) are in scope. + +Aspect Models express a schema with a defined Resource Description +Framework ([RDF](http://www.w3.org/TR/rdf11-concepts/)) vocabulary and are validated by a comprehensive +set of rules in the Shapes Constraint Language ([SHACL](https://www.w3.org/TR/shacl/)). Domain +semantics are captured by a combination of structural elements, relations, namespaces and reified named concepts. + +The Eclipse Semantic Modeling Framework (ESMF) in combination with the specifications of and open-source solutions for the Asset Administration Shell accelerates the development of digital twin technologies and drives its adoption in ecosystems. + +### 2.2 Semantic Aspect Meta Model + +The Semantic Aspect Meta Model (SAMM) provides a set of predefined +objects that allow a domain expert to define aspect models and +complement a digital twin with a semantic foundation. + +![SAMM 2.1.0](./assets/CX-0003-aspect-meta-model.jpg "Predefined SAMM Objects for Aspect Model Definition (Version +2.1.0)") + +The complete specification and further information about its +implementation and requirements can be accessed via the [Eclipse Semantic Modeling Framework (ESMF)][https://projects.eclipse.org/projects/dt.esmf](https://eclipse-esmf.github.io/samm-specification/snapshot/index.html). + +Every aspect model in +https://github.com/eclipse-tractusx/sldt-semantic-models that has +status "released" or "standardized" MUST be conformant to the +Semantic Aspect Meta Model. + +Every new aspect model MUST be conformant to the version of the Semantic +Aspect Meta Model as noted in the [normative reference](#31-normative-references) [SAMM](#2-semantic-aspect-meta-model-samm). + +### 2.3 Creation and Maintenance + +Every aspect model released or standardized in Catena-X MUST be maintained in Tractus-X: https://github.com/eclipse-tractusx/sldt-semantic-models. + +Every semantic model MUST have a unique identifier conformant to the meta model identifiers definition in [SAMM](#2-semantic-aspect-meta-model-samm). For the semantic models developed in the scope of Catena-X the unique identifier MUST start with + +``` +urn:samm:io.catenax. +``` + +Example for a unique identifier for an aspect model \"material for +recycling\": + +``` +urn:samm:io.catenax.material_for_recycling:1.0.0#MaterialForRecylcing +``` + +The governance process for new, updated or deprecated aspect models MUST be followed. The governance process for new, updated or deprecated aspect models is defined by Catena-X e.V. Additionally, the governance process is described directly in the github project: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/documentation/GOVERNANCE.md. + +NOTE: Older versions of already released or published aspect models MAY start with + +``` +urn:bamm:io.catenax +``` + +However, aspect models with prefix urn:bamm MUST not be used any longer. + +For migration of older aspect models see the [Migration guide](https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/bamm-migration.html). + +NOTE: SAMM was named BAMM until end of 2022 (BAMM for BAMM Aspect Meta Model). Renaming was executed in the context of the migration of the corresponding open source projects from Open Manufacturing Platform (OMP), a Linux Foundation project, to [Industrial Digital Twin Association (IDTA)](https://industrialdigitaltwin.org) and [Eclipse Foundation](https://www.eclipse.org/org/foundation/). + +### 2.4 Usage + +Every aspect of a digital twin registered in a digital twin registry +(see [CX-0002](CX-0002-DigitalTwinsInCatenaX)) accessible in the Catena-X data space MUST have a +semantic description (semantic ID) that is conformant to the unique aspect +model ID associated to it (see chapter [Creation and Maintenance](#23-creation-and-maintenance)). + +Example for semanticId: + +``` +urn:samm:io.catenax.material_for_recycling:1.0.0#MaterialForRecycling +``` + +## 3 References + +### 3.1 Normative References + +- [SAMM Semantic Aspect Meta Model, Version 2.1.0](https://eclipse-esmf.github.io/samm-specification/2.1.0/index.html). +- CX-0002 DIGITAL TWINS IN CATENA-X. Download in [Catena-X Standard Library](https://catena-x.net/de/tractus-x/standard-library). +- [Catena-X Operating Model Whitepaper](https://catena-x.net/fileadmin/user_upload/Publikationen_und_WhitePaper_des_Vereins/CX_Operating_Modelv2.1_final.pdf). Release V2.1 -- October 16, 2023. + +### 3.2 Non-Normative References + +*This section is non-normative* + +- [Semantic Data Structuring](https://raw.githubusercontent.com/OpenManufacturingPlatform/openmanufacturingplatform.github.io/master/docs/sds/OMP-Semantic-Data-Structuring-Whitepaper.pdf). Whitepaper. 2021-08-16. Open Manufacturing Platform. +- [Product Modeling with BAMM](https://github.com/OpenManufacturingPlatform/openmanufacturingplatform.github.io/raw/master/docs/sds/OMP-SDS-Product-Modeling-Whitepaper.pdf). Whitepaper. 2022-11-24. Open Manufacturing Platform. +- [ESMF Documentation](https://eclipse-esmf.github.io/esmf-documentation/). Eclipse Semantic Modeling Framework. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0003-SAMMSemanticAspectMetaModel/assets/CX-0003-aspect-meta-model.jpg b/docs/standards/CX-0003-SAMMSemanticAspectMetaModel/assets/CX-0003-aspect-meta-model.jpg new file mode 100644 index 000000000..6414114ae Binary files /dev/null and b/docs/standards/CX-0003-SAMMSemanticAspectMetaModel/assets/CX-0003-aspect-meta-model.jpg differ diff --git a/docs/standards/CX-0004-GovernanceProcess/CX-0004-GovernanceProcess.md b/docs/standards/CX-0004-GovernanceProcess/CX-0004-GovernanceProcess.md new file mode 100644 index 000000000..1fd09fc3b --- /dev/null +++ b/docs/standards/CX-0004-GovernanceProcess/CX-0004-GovernanceProcess.md @@ -0,0 +1,201 @@ +# CX-0004 Governance Process for Aspect models v1.0.1 + +## ABSTRACT + +This standard describes the governance process that shall be followed to +create, update or deprecate an aspect model. This process is the +prerequisite for any model submitted as a standardization candidate in +Catena-X. + +## 1. Introduction + +### 1.1 Audience & Scope + +> *This section is non-normative* + +This standard is relevant for + +- Business Application Provider +- Data Provider / Consumer +- Core Service Provider +- Enablement Service Provider +- Consulting Service Provider + +Some additional notes for stakeholders affected from governance of +semantic models: + +- Business application providers or business owners who are in need of new data that shall be exchanged and thus need new or updated aspect models need to be aware of the governance process of semantic models +- Business owners who want to deprecate an existing aspect model need to be aware of the governance process of semantic models +- Technical Committee for Standardization of Catena-X: only models that were created and maintained following the governance process as defined in this standard are allowed to be submitted as standardization candidates + +### 1.2 Context + +> *This section is non-normative* + +Catena-X standardized semantic models are an important enabler for +interoperability. Only when partners and business apps speak the \"same +language\", can data be exchanged seamlessly between use-cases and apps. +A semantic model that is standardized within Catena-X is needed when: + +- The consumer of the data isn\'t known prior to the data exchange +- Multiple consumers want to use the data +- The data is processed by various business apps in multiple use-cases + +The semantic models are included in the Semantic Hub. The Semantic hub provides a UI and search possibilities. + +### 1.3 Conformance + +As well as sections marked as non-normative, all authoring guidelines, +diagrams, examples, and notes in this specification are non-normative. +Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, +SHOULD and SHOULD NOT in this document are to be interpreted as +described in [BCP +14](https://datatracker.ietf.org/doc/html/bcp14) \[[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)\] +\[[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)\] when, and +only when, they appear in all capitals, as shown here. + +### 1.4 Proof of conformity + +> *This section is non-normative* + +All participants and their solutions will need to prove that they +conform to the Catena-X standards. To validate that the standards are +applied correctly, Catena-X employs Conformity Assessment Bodies (CAB). + +The resulting aspect models of modelling activities MUST be element of + +https://github.com/eclipse-tractusx/sldt-semantic-models with status +\"Released\". It MUST be ensured that all modelling stages were +successful. The modelling stages are ensured by github actions and +corresponding checklists (see also public documentation in github: +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/documentation/GOVERNANCE.md) + +### 1.5 Terminology + +> *This section is non-normative* + +**Aspect** + +a domain-specific view on information and functionality associated with +a specific **Digital Twin** with a reference to a concrete **Aspect +Model**. + +Note 1 to entry: An Aspect is a software service to retrieve the actual +runtime data of a **Digital Twin** (current or aggregated) from a data +source or to trigger operations. Thus, an aspect is built with an +implementation that ensures that the exchanged data is compliant to the +specification of the referenced **Aspect Model** via a defined +interface. + +Note 2 to entry: Aspects are registered (incl. their "API endpoint" +information) with the **Digital Twin** to which they belong in the +Digital Twin Registry. + +Note 3 to entry: an aspect corresponds to a **Submodel** in the **Asset +Administration Shell** + +**Aspect Model** + +a formal, machine-readable semantic description (expressed with +RDF/turtle) of data accessible from an **Aspect.** + +Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant with the validity rules defined by the Semantic Aspect Meta Model. + +Note 2 to entry: Aspect models are logical data models which can be used +to detail a conceptual model in order to describe the semantics of +runtime data related to a concept. Further, elements of an Aspect model +can/should refer to terms of a standardized Business Glossary (if +existing)​. + +Note 3 to entry: An Aspect Model describes the semantics of a Submodel. +A **Submodel Template** guides the creation of a **Submodel** conformant +to the Aspect Model and the **Asset Administration Shell**. + +**Asset Administration Shell** + +standardized digital representation of an asset + +Note 1 to entry: Asset Administration Shell and Administration Shell are +used synonymously. + +\[SOURCE: IEC 63278-1, note added\] + +**Digital Twin** + +digital representation, sufficient to meet the requirements of a set of +use cases + +Note 1 to entry: in this context, the entity in the definition of +digital representation is typically an asset. + +\[SOURCE: IIC Vocabulary IIC:IIVOC:V2.3:20201025, adapted (an asset, +process, or system was changed to an asset)\] + +**digital representation** + +information and services representing an entity from a given viewpoint + +EXAMPLE 1: examples of information are properties (e.g., maximum +temperature), actual parameters (e.g., actual velocity), events (e.g., +notification of status change), schematics (electrical), and +visualization information (2D and 3D drawings). + +EXAMPLE 2: examples of services are providing the history of the +configuration data, providing the actual velocity, and providing a +simulation. + +EXAMPLE 3: examples of viewpoints are mechanical, electrical, or +commercial characteristics. + +\[SOURCE: IEC 63278-1, editorial changes\] + +## 2. Governance Process for Aspect Models + +The governance process including its three modelling stages as described +in + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/documentation/GOVERNANCE.md +MUST be followed. The process includes guidance for new models, for +updating existing models and for deprecating existing semantic models. + +The Quality Gates for these three modelling stages are as follows: + +MS1_Approved, Checklist \"MS1 Request for Model Development\" is +approved. + +MS2_Approved, Checklist \"MS2 Valid Model\" is approved. + +MS3_Approved, Checklist \"MS3 Release Model\" is approved. The +associated pull request can be merged to the \"main-branch\". + +These Quality Gates MUST be fulfilled for the different modelling stages +of an aspect model. This includes conformance to CX-0003. + +Every aspect model MUST have a unique identifier. This identifier MUST +be used for registering an aspect/a submodel in the digital twin/the +Asset Administration Shell of a specific asset. For more details see +standards CX-0003 and CX-0002. + +## 3. References + +### 3.1 Normative References + +- CX-0002 DIGITAL TWINS IN CATENA-X +- CX-0003 SAMM SEMANTIC ASPECT META MODEL + +### 3.2 Reference Implementations + +> *This section is non-normative* + +The process is implemented in +https://github.com/eclipse-tractusx/sldt-semantic-models + +[^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf + +[^2]: https://catena-x.net/de/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0005-ItemRelationshipServiceAPI/CX-0005-ItemRelationshipServiceAPI.md b/docs/standards/CX-0005-ItemRelationshipServiceAPI/CX-0005-ItemRelationshipServiceAPI.md new file mode 100644 index 000000000..ba9c4ac4c --- /dev/null +++ b/docs/standards/CX-0005-ItemRelationshipServiceAPI/CX-0005-ItemRelationshipServiceAPI.md @@ -0,0 +1,256 @@ +# CX-0005 Item Relationship Service API 2.1.1 + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +> *Relevant only for existing standards. At the new standard, please delete* + +## ABSTRACT + +Today, a large amount of data is stored among different participants in a supply chain of an +industry. The value of the data can be enhanced immensely by connecting the data to their related +context. + +To enable cross-enterprise linked data, standards such as aspect models, standardized protocols, and +standardized ways to connect the data are applied. One of the first FOSS solutions to be developed +in Catena-X for accessing cross-enterprise linked data is the Item Relationship Service. This +document aims to standardize the API of the service so that any new participant can access this +interface to build new solutions based on data chains. Connected data, so-called data chains, are +seen as a valuable asset for the consortia that serve as an enabler technology for other Use-Cases +to build solutions on. + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +List for which roles the standard is relevant: + +- Core Service Provider +- Data Provider / Consumer +- Business Application Provider +- Enablement Service Provider +- Consulting Provider + +This Standard applies for Applications, which want to access Data Chains, and provide an +interoperable Solution for the Catena-X Network. To the time being of writing this document there +are Traceability Aspect Models which build data chains. So, this applies to the Traceability Business +Domain. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +This standardization is built upon existing standards, such as + +- “EDC Discovery API" [CX-0001] +- “Digital Twins in Catena-X“ [CX-0002] +- “SAMM Semantic Aspect Meta Model“ [CX-0003] +- “BusinessPartnerNumber“ [CX-0010] +- “Dataspace Connectivity v3.0.0” [CX-0018] +- “Implementation Specification: Data Provisioning for Release 2” [CX-0024] +- “Aspect Model: DataModelBoMAsSpecified“ [CX-0030] +- “Aspect Model: DataModelPartAsSpecified“ [CX-0032] +- “Aspect Model: PartSiteInformationAsPlanned" [CX-0094] +- “TraceabilityUseCase“ [CX-0125] +- "Industry Core: Part Instance" [CX-0127] +- "Industry Core: Part Type" [CX-0126] + +further Aspects which conclude in connecting Digital Twins between each other will be added to the Semantic Hub. + +The following aspect models are also relevant: + +- “Aspect Model: SingleLevelUsageAsBuilt" +- “Aspect Model: SingleLevelUsageAsPlanned" +- “Aspect Model: JustInSequencePart" +- “Aspect Model: PartSiteInformationAsBuilt" +- “Aspect Model: PartSiteInformationAsPlanned" + +Currently, no open Standard exists, which addresses this issue, based on the combination of the used +standards like Aspect Models, AAS (AssetAdministrationShell), EDC (Eclipse Dataspace Connector), and the Implementation specification it is a solution fit to the needs of Catena-X to simplify the interactions with data chains. + +This API has been designed to provide Interoperability within Catena-X on a Data Chain layer. Currently, +this is being developed in the Tractus-X Eclipse FOSS project. + +The IRS iterates through multiple digital twin aspects, which are representing a relationship. An example +aspect is the SingleLevelBOMasBuilt aspect, which connects serialized parts with each other, across company +boundaries. This service is accessing the aspects of digital twins for which an EDC policy and data contract +must exist. + +The following general conditions apply: + +- Access control through policies and contracts by the EDC +- Direct data exchange between supply-chain partners +- Catena-X partners of the accessible value chain are known to the data-consumer + +![irs-overview.svg](./assets/irs-overview.svg) +*Figure 1: IRS in iterative mode* + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative_ + +As well as sections marked as non-normative, all authoring guidelines, diagrams, +examples, and notes in this specification are non-normative. Everything else in +this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, +**REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be +interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they +appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform +with the Catena-X standards. To validate that the standards are applied +correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To prove conformity with the IRS API Standard provide the following assets to a conformity assessment +body: + +- API Response of the Implementation **MUST** match to the response structure of the API Documentation more information in the [Data Chain KIT](https://eclipse-tractusx.github.io/docs-kits/kits/Data%20Chain%20Kit/Adoption%20View%20Data%20Chain%20Kit) + +### 1.4 EXAMPLES + +Examples and further information are being shared in the [Data Chain KIT](https://eclipse-tractusx.github.io/docs-kits/kits/Data%20Chain%20Kit/Adoption%20View%20Data%20Chain%20Kit) +and in the [Tractus-X Github Repository](https://github.com/eclipse-tractusx/item-relationship-service) + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +Business Partner Number (BPN) +: A BPN is the unique identifier of a partner within Catena-X + +InternationalDataSpace(IDS) +: InternationalDataSpace and its protocol for data exchange foresees an compliant +connector handling contract negotiations before each data transfer and defines a general architecture for data exchange. + +EclipseDataspaceConnector(EDC) +: The EDC is a reference implementation for an IDS-compliant connector currently acting as a +de-facto standard and/or reference Implementation within Catena-X + +Additional terminology used in this standard can be looked up in the glossary on +the association homepage. + +## 2 Item Relationship Service API + +> *This section is normative* + +The IRS API follows the Apache 2.0 licenses. +The Item Relationship Service API is implemented as a RESTful API following the OpenAPI 3.0 specification +in JSON format. It covers initiating, retrieving, and controlling the lifecycle of a data chain +retrieval process. We use the OpenAPI standard to align on the industry standards for illustrating +RESTful APIs. + +## 2.1 PRECONDITIONS AND DEPENDENCIES + +The IRS API and the IRS App **MUST** be connected to an EDC in order to consume data offers within the Catena-X data space. It will handle the access and usage control so that a data sovereign data space can be provided + +The data accessed and consolidated via the IRS **MUST** be accessible via EDC Assets by data providers; +“Dataspace Connectivity v3.0.0” [CX-0018] and be registered via the Registry Service (Digital Twin Registry) [CX–0002]. + +The Aspects to traverse along data chains are built upon the data chain aspect template. Aspect models such as the SingleLevelBOMasBuilt is built upon that. The IRS API uses that information to build connected data chains. +To find the correct assets within a data space the Digital Twin registry is beeing used. These preconditions need to be met, so that the IRS API works accordingly. + +## 2.2 API SPECIFICATION + +### 2.2.1 API ENDPOINTS & RESOURCES + +The openAPI documentation is formulated here [IRS API 4.5.2]([IRS API](https://github.com/eclipse-tractusx/item-relationship-service/blob/4.5.2/docs/src/api/irs-api.yaml)) +The following Endpoints **MUST** be implemented as described in the openAPI document: + +- ItemRelationshipService + - GET /irs/jobs + - POST /irs/jobs + - GET /irs/jobs/\{id\} + - PUT /irs/jobs/\{id\} + - POST /irs/orders + - GET /irs/orders/\{orderId\} + - PUT /irs/orders/\{orderId\} + - GET /irs/orders/\{orderId\}/batches/\{batchId\} + +The following Endpoints **OPTIONAL** be implemented as described in the openAPI document: + +- ItemRelationshipService + - GET /irs/policies + - POST /irs/policies + - PUT /irs/policies/\{policyId\} + - DELETE /irs/policies/\{policyId\} + +The following Endpoints **OPTIONAL** be implemented as described in the openAPI document: + +- EnvironmentalAndSocialStandards + - POST /ess/bpn/investigations + - GET /ess/bpn/investigations/\{id\} + - POST /ess/notification/receive + - POST /irs/ess/orders + +- AspectModels + - GET /irs/aspectmodels + +### 2.2.2 AVAILABLE DATA TYPES + +The API **MUST** use JSON as the payload transported via HTTPS(TLS). + +### 2.2.3 EDC DATA ASSET STRUCTURE + +Not applicable for this document + +### 2.2.4 ERROR HANDLING + +The following http response codes **MUST** be defined for IRS API endpoints: + +- **200:** The request succeeded +- **201:** The request succeeded and returns the expected result +- **206:** This is sent when a partial result of a resource is being sent. +- **400:** Bad Request - Requested operation in failed state. +- **401:** Unauthorized - No valid authentication credentials. +- **403:** Forbidden - Authorization refused by server. +- **404:** Not Found - Requested resource not found + +[IRS API 4.5.2]([IRS API](https://github.com/eclipse-tractusx/item-relationship-service/blob/4.5.2/docs/src/api/irs-api.yaml)) +More information for each endpoint can be extracted from the IRS API documentation. + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +- Digital Twins in Catena-X [CX–0002] +- Dataspace Connectivity v3.0.0 [CX-0018] +- Implementation Specification: Data Provisioning for Release 2 [CX-0024] +- TraceabilityDataProvisioningBoMAs-PlannedTriangle [CX-0061] +- “TraceabilityUseCase“ [CX-0125] + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- “Aspect Model: DataModelBoMAsSpecified“ [CX-0030] +- “Aspect Model: DataModelPartAsSpecified“ [CX-0032] +- “AspectModel: PartSiteInformationAsPlanned“ [CX-0094] +- "IndustryCorePartInstance" [CX-0127] +- "IndustryCorePartType" [CX-0126] + +- [Item Relationship Service (Publication on website)](https://catena-x.net/en/offers-standards/item-relationship-service) + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +The code found at [https://github.com/eclipse-tractusx/item-relationship-service](https://github.com/eclipse-tractusx/item-relationship-service) +represents a reference implementation that implements this standard. + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0005-ItemRelationshipServiceAPI/assets/irs-overview.svg b/docs/standards/CX-0005-ItemRelationshipServiceAPI/assets/irs-overview.svg new file mode 100644 index 000000000..0466bd358 --- /dev/null +++ b/docs/standards/CX-0005-ItemRelationshipServiceAPI/assets/irs-overview.svg @@ -0,0 +1,538 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/standards/CX-0006-RegistrationAndInitialOnboarding/CX-0006-RegistrationAndInitialOnboarding.md b/docs/standards/CX-0006-RegistrationAndInitialOnboarding/CX-0006-RegistrationAndInitialOnboarding.md new file mode 100644 index 000000000..25f6e1e71 --- /dev/null +++ b/docs/standards/CX-0006-RegistrationAndInitialOnboarding/CX-0006-RegistrationAndInitialOnboarding.md @@ -0,0 +1,380 @@ +# CX-0006 Registration and Initial Onboarding v2.0.0 + +## ABSTRACT + +To become a participant of Catena-X, each applicant must go through a +registration process. Registration is a mandatory requirement for all further +activities within the Catena-X network. The registration process, along with other +services, provide the foundation of trust for the Catena-X network. + +## FOR WHOM IS THE STANDARD DESIGNED + +This standard is relevant for the following roles: + +- Core Service Provider +- Onboarding Service Provider + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +| Version | Change by | Change Details | +|---------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 2.0.0 | Julia Jeroch | Updated following chapters:
- 2.3.4 Company Data Validation
- 2.3.8 Gaia-X

And added:
- 2.3.5 Business Partner Number Creation
- 2.3.6 Wallet Tenant Creation
- 2.3.7 Credential Storage
- 2.3.9 Registration Approval and Dataspace Access | + +## 1 INTRODUCTION + +The document deals with the initial registration process which is the initial +mandatory step for new Catena-X network participants. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following roles: + +- Core Service Provider +- Onboarding Service Provider + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +In order to register participants, the Core Service Provider operates a registration service where a registering company can enter its details to initiate the registration process. + +The interaction between Core Service Provider and Onboarding Service Provider is defined in this standard. + +Figure 1 shows a high-level view of a section of Catena-X. It consists of the +following building blocks: + +- Catena-X Core Services -- Basic services, like for example discovery + services, used by all participants of Catena-X. The core services are + standardized by the Catena-X consortium. + +- Participants environments -- A participant can offer and consume + data. For this, he needs an Eclipse Dataspace Connector as well as + corresponding prosumer applications. The applications are provided + by Catena-X application providers. + +- The Gaia-X Digital Clearing House (GXDCH) consists of a notarization + service and a compliance service and can be operated by another + party. GXDCH is a Gaia-X component and must therefore comply with + the corresponding Gaia-X standards. GXDCH on the one hand verifies + the legitimacy of Catena-X participants and on the other hand it + ensures the creation of Gaia-X compliant self-descriptions. + +![CX-0006-high-level-view1.jpg](./assets/CX-0006-high-level-view1.jpg) + +Figure 1 High-level view of a section of Catena-X + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +The registration process described in this document serves as reference +for future implementations. Core service providers and Onboarding Service Providers implementing +their own registration solution MUST demonstrate compliance by: + +- Providing documentation of the registration process implemented. +- Proofing that the registration process includes all the mandatory steps as defined in this standard. +- Proofing that the registration process implemented delivers the mandatory results as detailed in this standard. + +## 2 THE REGISTRATION PROCESS + +### 2.1 CONTEXTUAL DESCRIPTION + +To become a participant of Catena-X, each applicant must go through a +registration process. Registration is a mandatory requirement for all +further activities within the Catena-X network. The registration +process, along with other services, provide the foundation of trust for +the Catena-X network. + +### 2.2 ACTORS AND ROLES + +|Actors|| +|---|---| +|The to be onboarded company |The company that wants to register to Catena-X| +|Core Service Provider|Core Service Providers run core services that enable the basic functionality of the Catena-X data space (e.g., Identity Provider, Discovery Services). They can also act as an Onboarding service provider.| +|Onboarding service provider| Onboarding Service Providers enable data provider/consumer to be registered to the Catena-X network.| + +### 2.3 PROCESS REPRESENTATION + +![CX-0006-catenax-registration2.jpg](./assets/CX-0006-catenax-registration2.jpg) + +Figure 2: Catena-X Registration Process + +--- + +#### 2.3.1 Initial Contact - non normative** + +Catena-X follows an invitation-based registration process. Companies can contact Catena-X in one of +the following ways: + +- A current member of Catena-X proposes another company as a candidate +- Candidates are approached at trade fairs or other events +- Companies contacting Catena-X via the Catena-X homepage + +--- + +#### 2.3.2 Invite + +An Onboarding service provider **MAY** send an invitation mail to the previously identified contact +person of the company to be invited. The mail grants temporary access to the registration tool +of Onboarding service provider. + +--- + +#### 2.3.3.1 Company Data Collection + +During the company registration process, the following data **MUST** get collected from the to be onboarded customer: + +- Company Name +- Street + House number/Postbox +- Postal Code (depending on country) +- City +- Country +- Unique Identifier (based on country - see Upload excerpt from commercial register or equivalent + for more information) +- Region / State (optional - depending on country + +This can be done either manually or partially automatically if the master data for the company is +already contained in BPDM which is the central business partner directory of Catena-X. At least the +data necessary for creating a business partner entry in BPDM must be provided. For additional +information refer to BPM-001 Business Partner Number and BPM-002 Issuing Agency. + +--- + +#### 2.3.3.2 Select company role inside the Catena-X network + +The to be onboarded company **MUST** be able to select at least one of the following roles: + +- Active Participant + - The participant role is covering the data provider, data consumer or app user scenario. As + participant you are an active member of the network with enabled services to particiapte as + contributer and user. +- App Provider + - The App Provider is a company which is providing application software via the CX marketplace. As + app provider you can participate and use the developer hub, release and offer applications to the + network and manage your applications. +- Service Provider + - The Service Provider is able to offer 3rd party services, such as dataspace service offerings to + CX Members. CX members can subscribe for those services. +- Onboarding Service Provider + - An Onboarding Service Provider is a company that helps other companies register with Catena-X for the first time. + +There may be other roles in the future. + +--- + +#### 2.3.3.3 Agree to terms and conditions + +The to be onboarded company **MUST** accept the framework agreement, which consists of the operator +terms, dataspace terms and CX terms (depending on the selected company role). + +--- + +#### 2.3.3.4 Proof of conformity + +Each application or service provider **MUST** be able to proof conformity with relevant standards +for the selected company role. Conformity is assessed by an external conformity assessment body +(CAB). The to be onboarded company **MUST** first complete the conformity assessment and need to be +enabled to provide the certificate of conformity as part of the registration application. + +--- + +#### 2.3.3.5 Upload excerpt from commercial register or equivalent + +Each company to be onboarded **MUST** be enabled to provide proof of identity in the form of an +extract from the commercial register or equivalent (depending on the legal entity location of the +to be onboarded company). + +Catena-X **SHOULD** support the following identifiers specified by Gaia-X Trust Framework 22.10 (http://docs.gaia-x.eu/policy-rules-committee/trust-framework/22.10/participant/). + +|Identifier|Comment|Example| +|-|-|-| +|local|The state issued company number|HRB 123456 (German commercial registration number)| +|VAT ID|The VAT identification number|DE 123456789 (German VAT ID)| +|LEI Code|Unique LEI number as defined by https://www.gleif.org.|123400789abcde123420 (20 digit alpha numeric code)| +|EORI|The Economic Operators Registration and Identification number (EORI)|DE1234567891234567| + +--- + +#### 2.3.3.6 Submit registration + +Onboarding service providers and core service providers **MUST** provide a mechanism for submitting +the registration and triggering subsequent activities. + +--- + +#### 2.3.4 Company Data Validation + +Once the company data are collected, it must be validated to ensure accuracy and completeness. The following validation checks **MUST** be performed: + +- Verify that all required fields are filled out +- Validate the format and accuracy of the unique identifier +- Validate proof of conformity of the registering company +- CSPs should implement robust validation mechanisms to ensure the integrity of the company data. +- In order to avoid duplicates, onboarding service providers / core service providers **MUST** check +whether the company to be onboarded is already registered. + +#### 2.3.5 Business Partner Number Creation + +After the company data is validated, a unique business partner number must be generated for the registered company (if not already existing). The business partner number serves as a unique identifier for the company within the dataspace. +The generation of the BPN as well as the to-be-used algorithm is covered in the business partner number standard. + +- Onboarding service providers / core service providers **MUST** ensure that a Business Partner Number (BPN) exists or is created and linked to the company being registered. + +#### 2.3.6 Wallet Tenant Creation + +A wallet tenant needs to be created for the registered company. A wallet tenant allows the company to securely store and manage digital credentials and assets in their own separated tenant/instance. +CSPs and OSPs should have a mechanism in place to create a wallet tenant associated with the registered company. The wallet tenant should be securely provisioned and accessible only to authorized individuals. + +- Onboarding service providers / core service providers **MUST** ensure that a Managed Identity Wallet is created for the company to be onboarded. The BPN **MUST** be stored in the Managed Identity Wallet as a verifiable credential and serves as a unique ID. + +#### 2.3.7 Credential Storage + +As part of the registration process, the company's credentials (e.g., digital certificates, authentication tokens) must be securely stored. These credentials are used for authentication and authorization purposes. +CSPs should implement secure storage mechanisms to protect the company's credentials from unauthorized access or tampering. + +#### 2.3.8 Gaia-X + +- Onboarding service providers / core service providers **MUST** ensure that a company compliance check is executed by an official Gaia-X Digital Clearing House (GXDCH). In alignment with onboarding +service providers / core service providers, GXDCH issues verifiable credentials. +- Onboarding service providers / core service providers **MUST** ensure the creation of a Self-Description (SD) of the Legal Person as part of the application verification process. +The SD **MUST** be stored in a central location and **MUST** be in line with the GAIA-X standards/guidelines. + +#### 2.3.9 Registration Approval and Dataspace Access + +- Only when all checks have been successfully passed, the onboarding service providers / core service providers **MUST** provide access to the services. If one or several application validation steps have not been passed, the onboarding service providers / core service providers **MUST** reject the registration or defer it for revision. +- Onboarding service providers / core service providers **MUST** provide feedback (success/rejection/revision) to the to be registered company. + +### 2.4 TECHNICAL INTEGRATION + +Onboarding service providers / core service providers **MUST** provide onboarding companies with +information on the step required to complete technical onboarding (connector registration, technical user creation, etc.). + +Onboarding service providers / core service providers **MAY** support with the technical onboarding +(integration of corporate identity provider, connector registration, technical user creation, etc.). + +## 3. ONBOARDING SERVICE PROVIDER + +An Onboarding Service Provider helps companies register at Catena-X for the first time. +The motivation for this may be that an onboarding service provider wants to make it easier for its +own customers to get onboarded to Catena-X, or to make the Catena-X onboarding process smoother in +general. The to be onboarded company only interacts with the Onboarding Service Provider for registration. + +This chapter describes how to enroll on Catena-X with the help of an Onboarding Service Provider. + +### 3.1 HOW TO BECOME AN ONBOARDING SERVICE PROVIDER + +- The Onboarding Service Provider **MUST** fulfill the conformance criterias defined in +CX – 0008 RELEVANT STANDARDS FOR CONFORMITY ASSESSMENT +- The Onboarding Service Provider **MUST** implement a registration process that complies with the +registration process defined in this document. +- Core Service Provider and Onboarding Service Provider **MUST** have a contractual relationship +which considers / respects / includes Catena-X standards, principles and data processing. To enable +the Onboarding Service Provider to act on behalf of the Core Service Provider. +- Core Service Provider and Onboarding Service Provider **MUST** implement registration interfaces according to CX - 0009 CATENA-X REGISTRATION API. +- The Core Service Provider **MUST** validate the Onboarding Service Provider trustability and +validate the implemented data security processes. For example + - Sensitive data - such as access credentials - **MUST** be secured using state-of-the-art methods. + - Registration tools provided by the onboarding service **MUST** be secured against security vulnerabilities. +- The Core Service Provider **MUST** provide Onboarding Service Providers secure access to the +registration API. +- The Onboarding Service Provider **MUST** register as an Onboarding Service Provider with a Core Service Provider. Company role is "Onboarding Service Provider". +- The Core Service Provider **MUST** process and validate Catena-X registration requests initiated by third parties and submitted by the Onboarding Service Provider. This includes the sending of a registration status notification response back to the Onboarding Service Provider (see 6 - 8 in Figure 3). + +### 3.2 ONBOARDING TO CATENA-X WITH AN ONBOARDING SERVICE PROVIDER + +The sequence diagram below depicts an exemplary registration flow through an Onboarding Service Provider. + +```plantuml +@startuml + +title "Exemplary registration flow using a Onboarding Service Provider" + +"To be onboarded company" -> "Onboarding Service Provider" : 1.) Register at Onboarding Service Provider +"To be onboarded company" -> "Onboarding Service Provider" : 2.) Requests registration at Catena-X and agrees to submit data to the Core Service Provider +"Onboarding Service Provider" -> "Core Service Provider" : 3.) POST registration/network/partnerRegistration +"Core Service Provider" -> "To be onboarded company" : 4.) Email to confirm Terms & Conditions and finally submit the registration +"To be onboarded company" -> "Core Service Provider" : 5.) Confirm Terms & Conditions and offically submit the registration request +"Core Service Provider" -> "Onboarding Service Provider" : 6.) POST back registration status ("Submitted" or validation error") +"Core Service Provider" -> "Core Service Provider" : 7.) Internal validation and processing of registration request +"Core Service Provider" -> "Onboarding Service Provider" : 8.) POST back registration status ("Approved", "Decline", "Error") +"Core Service Provider" -> "To be onboarded company" : 9.) Send back registration status ("Approved", "Decline", "Error") - including instructions how to access Catena-X + +@enduml +``` + +Figure 3: Exemplary registration flow using a Onboarding Service Provider + +The registration API is specified in CX - 0009 CATENA-X REGISTRATION API. + +**Who may register with Catena-X using an Onboarding Service Provider** + +The Onboarding Service Provider **SHOULD** only allow companies that add value to Catena-X to +register for Catena-X. There are no defined rules for this, so it is up to the provider to decide. +The Core Service Provider is free to refuse registration requests to Catena-X. + +**The Onboarding Service Provider is no longer offering the services** + +In the event that the Onboarding Service Provider ceases to provide its service, the Onboarding +Service Provider and the Core Service Provider **MUST** agree on and apply a migration process +allowing to follow audit regulations and to enable all customers to remain actively in the dataspace. + +**Offboarding from Catena-X using an Onboarding Service Provider** + +The Onboarding Service Provider **MUST** provide an offboarding service that complies with the +Catena-X offboarding standard (currently under development). + +## 4 REFERENCES + +### 4.1 NORMATIVE REFERENCES + +- CX-0009:2.0 CATENA-X REGISTRATION API +- CX-0010:1.1 BUSINESS PARTNER NUMBER (BPN) +- CX-0011:1.0 ISSUING AGENCY +- CX-0013:2.0 IDENTITY OF MEMBER COMPANIES + +### 4.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- Gaia-X Trust Framework\ + (https://gaia-x.gitlab.io/policy-rules-committee/trust-framework/) + +- Gaia-X Framework (https://docs.gaia-x.eu/framework/) + +- GXDCH (https://gaia-x.eu/gxdch/) + +### 4.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +The code found at: + +- https://github.com/eclipse-tractusx/portal-backend + +presents a reference implementation that implements this standard. + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +- Figure 1 High-level view of a section of Catena-X +- Figure 2: Catena-X Registration Process +- Figure 3: Exemplary registration flow using a Onboarding Service Provider + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0006-RegistrationAndInitialOnboarding/assets/CX-0006-catenax-registration2.jpg b/docs/standards/CX-0006-RegistrationAndInitialOnboarding/assets/CX-0006-catenax-registration2.jpg new file mode 100644 index 000000000..e8f33e8fe Binary files /dev/null and b/docs/standards/CX-0006-RegistrationAndInitialOnboarding/assets/CX-0006-catenax-registration2.jpg differ diff --git a/docs/standards/CX-0006-RegistrationAndInitialOnboarding/assets/CX-0006-high-level-view1.jpg b/docs/standards/CX-0006-RegistrationAndInitialOnboarding/assets/CX-0006-high-level-view1.jpg new file mode 100644 index 000000000..37a92d615 Binary files /dev/null and b/docs/standards/CX-0006-RegistrationAndInitialOnboarding/assets/CX-0006-high-level-view1.jpg differ diff --git a/docs/standards/CX-0006-RegistrationAndInitialOnboarding/metadata.json b/docs/standards/CX-0006-RegistrationAndInitialOnboarding/metadata.json new file mode 100644 index 000000000..753036696 --- /dev/null +++ b/docs/standards/CX-0006-RegistrationAndInitialOnboarding/metadata.json @@ -0,0 +1 @@ +{"id":"b25ed299-da9d-4991-9e41-48407c9d3cba","numberId":"CR-CX-49","architectCompany1":"SAP","architectCompany2":" ","architectCompany3":" ","architectCompany4":" ","architectCompany5":" ","architectEmail1":"andreas.hess01@sap.com","architectEmail2":" ","architectEmail3":" ","architectEmail4":" ","architectEmail5":" ","architectGithub1":"ahess99","architectGithub2":" ","architectGithub3":" ","architectGithub4":" ","architectGithub5":" ","architectName1":"Andreas Hess","architectName2":" ","architectName3":" ","architectName4":" ","architectName5":" ","audiences":["CORE_SERVICE_PROVIDER","ONBOARDING_SERVICE_PROVIDER"],"businessDomain":"ONBOARDING","changelog":"The Onboarding Service Provider flow is now implemented and should be covered in the standard document to enable the collaboration between the OSP and CSP.","directoryName":"CX-0006-RegistrationAndInitialOnboarding ","evaluationsOfAlternatives":"-","involvedCompany1":"BMW","involvedCompany2":"SupplyOn","involvedCompany3":"SAP","involvedCompany4":"VW","involvedCompany5":" ","involvedCompany6":" ","involvedCompany7":" ","involvedCompany8":" ","involvedCompany9":" ","involvedCompany10":" ","involvedCompany11":" ","involvedCompany12":" ","involvedCompany13":" ","involvedCompany14":" ","involvedCompany15":" ","involvedCompany16":" ","involvedCompany17":" ","involvedCompany18":" ","involvedCompany19":" ","involvedCompany20":" ","managementSummary":"The Onboarding Service Provider flow is now implemented and should be covered in the standard document to enable the collaboration between the OSP and CSP.","name":"Registration and initial onboarding","otherBusinessDomain":" ","otherPlatformCapability":" ","otherScope":"Onboarding and collaboration between Core Service Provider (CSP) and Onboarding Service Provider (OSP)","otherUseCase":"Use case agnostic","ownerCompany1":"SAP","ownerCompany2":"BMW","ownerCompany3":" ","ownerCompany4":" ","ownerCompany5":" ","ownerEmail1":"andreas.hess01@sap.com","ownerEmail2":"julia.jeroch@bmw.de","ownerEmail3":" ","ownerEmail4":" ","ownerEmail5":" ","ownerGithub1":"ahess99","ownerGithub2":"jjeroch","ownerGithub3":" ","ownerGithub4":" ","ownerGithub5":" ","ownerName1":"Andreas Hess","ownerName2":"Julia Jeroch","ownerName3":" ","ownerName4":" ","ownerName5":" ","platformCapability":null,"problemStatement":"Enhancement of onboarding flow for Onboarding Service Provider enablement.","productOwnerCompany1":"BMW","productOwnerCompany2":"VW","productOwnerCompany3":"","productOwnerCompany4":" ","productOwnerCompany5":" ","productOwnerEmail1":"julia.jeroch@bmw.de","productOwnerEmail2":"steffen.poetsch@vw.de","productOwnerEmail3":" ","productOwnerEmail4":" ","productOwnerEmail5":" ","productOwnerGithub1":"jjeroch","productOwnerGithub2":" ","productOwnerGithub3":" ","productOwnerGithub4":" ","productOwnerGithub5":" ","productOwnerName1":"Julia Jeroch","productOwnerName2":"Steffen Pötsch","productOwnerName3":" ","productOwnerName4":" ","productOwnerName5":" ","purpose":"Enhancement of onboarding flow for Onboarding Service Provider enablement.","scope":"OTHER","standardType":"BUSINESS","status":"IN_PROGRESS","useCase":"OTHER","version":"1.1.3","createdAt":"2023-09-25T13:00:35.074Z","updatedAt":"2023-09-25T15:40:02.408Z"} \ No newline at end of file diff --git a/docs/standards/CX-0007-MinimalDataProviderServicesOffering/CX-0007-MinimalDataProviderServicesOffering.md b/docs/standards/CX-0007-MinimalDataProviderServicesOffering/CX-0007-MinimalDataProviderServicesOffering.md new file mode 100644 index 000000000..7e243659a --- /dev/null +++ b/docs/standards/CX-0007-MinimalDataProviderServicesOffering/CX-0007-MinimalDataProviderServicesOffering.md @@ -0,0 +1,488 @@ + +# CX-0007 Minimal Data Provider Service Offering v1.0.2 + +## ABSTRACT + +Data provisioning is one of the key success factors for a data space, as +without data offers, there is nothing to consume with the various +business applications that data consumers will use. While it is +relatively easy for large enterprises with extensive IT capabilities to +connect their backend systems to the Catena-X landscape, providing data +is a challenging task for SMEs and non-tech savvy companies. Thus, +simple to use tools for data provisioning -- such as excel upload tools +-- are needed, which can be operated by regular employees without +sophisticated IT skills. + +## 1. INTRODUCTION + +Data provisioning is one of the key success factors for a data space, as +without data offers, there is nothing to consume with the various +business applications that data consumers will use. While it is +relatively easy for large enterprises with extensive IT capabilities to +connect their backend systems to the Catena-X landscape, providing data +is a challenging task for SMEs and non-tech savvy companies. Thus, +simple to use tools for data provisioning -- such as excel upload tools +-- are needed, which can be operated by regular employees without +sophisticated IT skills. + +The purpose of this document is to describe the necessary functional +building blocks of a minimal data provider service, as well as to give +an overview over the interplay of necessary standards that need to be +considered. The document also gives an overview over the mandatory +standards that need to be integrated. Service offerings for data +providers that do not fulfil the necessary standards and concepts in +this document, will not work in the Catena-X network and thus cannot be +provided to any customer. In the following chapters, the minimal data +provider service will also be referred to as "upload tool" for better +understandability. + +Minimal data provider service offerings will in the following also be referred to as +"upload tools" or "data provisioning tools". + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +The target audience of this standard is any application or service provider that wants to offer services related to one time data provisioning, such as but not limited to, manual text masks or file-based uploads. It is not intended to explain how continuous backend integrations of e.g. ERP or MES systems into the Catena-X network can work. Please refer to CX-0055 for this. This standard applies to data provisioning for all Catena-X Use-Cases. + +This document is relevant for the following roles: + +- Enablement Service Provider +- Business Application Provider + +Only, if they plan to provide one time data upload capabilities as +part of their business applications + +### 1.2 CONTEXT + +> *This section is non-normative* + +Catena-X is a decentral network where data exchange happens P2P between +two parties. This guarantees a high level of data sovereignty, as data +providers and consumers do not rely on a third party or a platform to +exchange data. Also, business apps within Catena-X are built to be +interoperable along the value chain, so that different participants can +use different apps from various providers, but still are able to +exchange data between them. To enable the network, a common technological basis is needed. + +Data is described with a standardized semantic, which is specific for +each Use-Case. The semantics are described with the semantic modeling +language SAMM. + +Furthermore, data discovery and access is enabled by the Asset Administration Shell (Digital Twins), +or by knowledge agents. + +The data exchange itself happens in a self-sovereign way via the EDC.   + +Any tool that is built to provide data, needs to fulfill use-case +specific (semantic models, calculation logic, etc.) and independent (e.g. use of EDC, IAM Concept) +standards. The use-case specific standards are listed in a "Use-Case Policy" and +are available via the association homepage. + +Of specific importance for data provisioning tools is the concept of data sovereignty. +Data sovereignty is one of the core values of the Catena-X network. Each +participant should stay in as much control as possible over his data. +This includes that he always exactly knows with whom he is exchanging +data. The participant also can decide on a dataset level, which of his +partners is able to see the various data offers (Access Policies) and +then decide under which conditions he is willing to share data (Usage +Policies). Furthermore, the user of the upload tool must be able to +update or delete the actual data, access and usage policies as well as +any meta data and references to data. + +A data provisioning tool, as described in the next section, must make sure that +the user of that tool gets to this level of data sovereignty by +implementing features that allow him to choose which data he is willing +to share with whom under which conditions, and also change those +settings as he wishes. Upload tools that can't fulfill these +requirements, can't be sold to customers as they contradict one of the +key values of Catena-X. + +### 1.3 ARCHITECTURE OVERVIEW + +![Architecture Overview](./assets/CX-0007-picture1.png) + +Figure 1:Architecture Overview + +The architecture of a minimal data provider service offering is simple. +It consists of and interacts with the following components. + +#### 1.3.1 FRONTEND + +The frontend is the entry point into the service. It's used by the end +user of a data provider who won't interact with any backend system or +other related components via CLI or API. + +#### 1.3.2 BACKEND + +The backend is responsible for orchestrating the various needed +interactions with other components. It needs to handle the upload of +data into the data persistence layer, create/delete/update the EDC contract +offer, (De-)register data at the digital twin +registry, handle authentication and authorization at the application and +so on and so forth. + +#### 1.3.3 DATA PERSISTANCE LAYER + +The uploaded data needs to be persisted in an appropriate database +solution, so that it can be received upon request. Depending on the data +and the use-case, this could be a SQL, No-SQL, S3 or streaming storage. + +Note: It is not enough to register a digital twin or create an EDC +contract offer as they only contain meta-data and references to the +actual data. The actual data also needs to be made available after it +has been uploaded to the tool. That is the responsibility of the data +persistence layer. + +#### 1.3.4 EDC + +The EDC is a separate component that is needed to enable a sovereign +data exchange. There's currently no data provisioning for the various +use cases without an EDC. The EDC always needs to be deployed together +with the front- and backend. Also, the EDC currently isn't tenant +isolated, thus one EDC needs to be deployed per customer company. + +As an alternative, the solution can be configurable with an external EDC. + +Furthermore, the EDC that is used must be discoverable by data consumers and thus +be registered at the EDC discovery service. + +#### 1.3.5 DIGITAL TWIN REGISTRY (DTR) + +Starting with release 3.2, the DTR is a decentral component +that must be implemented with each data provider. +It stores references to aspects of digital twins. +The actual data ("the digital twin") is stored in the data persistence layer +that comes with a minimal data provider service. The backend needs to +interact with the decentral DTR to register newly created/uploaded twins. +In case a user deletes data, the backend also needs to de-register the twins +again. For an API description of the DTR, refer to CX-0002. + +A minimal data provider service offering either must include its own +decentral DTR or it can be configurable to work with an external decentral DTR. + +Furthermore, the DTR that is used must be discoverable by data consumers and thus +be registered at the discovery finder and #TODO Discovery finder + +#### 1.3.6 SSI INTEGRATION + +The upload tool must be able to interact with the Catena-X SSI solution to +provide the correct attributes and roles of a data provider to the EDC. + +#### 1.3.7 SEMANTIC MODELLING LANGUAGES AND MODELS + +Depending on the use-case, different semantic modelling languages and +semantic models need to be understood by the upload tool. E.g.: if the +upload tool wants to work for the use-case traceability, the tool needs +to be able to process the Aspect Model: SerialPartTypization in the SAMM +language. + +Note: SAMM is currently the only modeling language that is used within +Catena-X. When this changes in the future, this standard will be updated +to also reference other modelling languages. + +The semantic modelling languages and models that are used within a +use-case can be found within the "Use Case Policy" for each use-case. +It's mandatory for the tool to function with those semantic modelling +languages and semantic models. + +A list of all released semantic models can be found in Github: https://github.com/eclipse-tractusx/sldt-semantic-models. + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, +diagrams, examples, and notes in this specification are non-normative. +Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, +SHOULD and SHOULD NOT in this document are to be interpreted as +described in [BCP +14](https://datatracker.ietf.org/doc/html/bcp14) \[[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)\] +\[[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)\] when, and +only when, they appear in all capitals, as shown here. + +### 1.5 Proof of conformity + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they are +conform with the Catena-X standards. To validate that the standards are +applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). +Please refer to the association homepage for the process of conformity +assessment and certification. + +Enablement Service Providers and Business application providers need to +provide the following to the CAB:   + +- High level architecture document describing the various components of the solution and their interplay +- Functional Specification / Pflichtenheft describing how the functional and non-functional requirements stated in chapter 2.2 shall be fulfilled. +- Proof that the service offering fulfills all of the standards listed in chapter 2.1 + +The partner collects the requested documents and results and sends them to the responsible CAB. The CAB might also conduct an external audit to assess conformance with the standards. The responsible CABs can be found on the homepage of the association: [www.catena-x.net](http://www.catena-x.net/). + +The solution can only be listed in an official Catena-X Marketplace after successful verification of conformity. + +## 2. MINIMAL DATA PROVIDER SERVICE OFFERING + +All requirements that are listed as "mandatory" under chapter 2.2 MUST generally be +fulfilled by a service offering. If a service offering does not fulfill +a mandatory requirement, the provider offering the service MUST +explain why he derives from the requirement. It is then up to the CAB to +decide if the service offering still receives a certificate. + +All requirements that are listed as "optional" SHOULD be fulfilled by a +service offering. + +The specific standards listed in chapter 2.1 MUST be implemented correctly. + +## 2.1 ADHERENCE TO SPECIFIC STANDARDS + +The following use-case agnostic standards MUST be implemented correctly. +More details can be found in the respective individual standards: + +- CX-0013 Identity of Member Companies +- CX-0016 Company Attribute Verification +- CX-0017 Company Role by the Connector +- CX-0018 Eclipse Data Space Connector (EDC) + +Depending on the use-cases for which the service offering is intended, +additional and use-case specific standards are relevant and MUST be implemented. +Please refer to the use-case specific standards therefore.   + +E.g. if the Minimal Data Provider Service Offering is intended to work for the traceability use-case, +conformance with the standards that are listed in the "Use-Case Policy Traceability" must be shown. +This includes: + +- CX-0019 Aspect Model: Serial Part Typization +- CX-0020 Aspect Model: Aspect Model: Assembly Part Relationship +- CX-0021 Aspect Model: Batch +- CX-0022 Notification Process +- CX-0002 Digital Twins in Catena-X + +NOTE: The enablement service provider CAN also choose to provide the option to configure an existing +EDC, DTR or other decentral component with the upload tool instead of including it with the offer. +However, he MUST provide one of the two options. + +As long as not specified differently, the latest version of the standards MUST be applied. + +## 2.2 FUNCTIONAL & NON-FUNCTIONAL BUILDING BLOCKS + +| ID \| Obligation | Title | +|-----------------------------------------------------------------------------------------------------------------------------------------|---------------| +| FR-00 \| Mandatory | Login | +| Description | | +| As a user, I want to login to the tool with a username and password so that the tool is protected from unauthorized access. | | + +| ID \| Obligation | Title | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| +| FR-01 \| Optional | Single Sign-On | +| Description | | +| As a user, I want to login to the tool with my known credentials from e.g. the CX Platform or my company internal IDP so that I don’t need to remember an extra set of credentials. | | + +| ID \| Obligation | Title | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------| +| FR-02 \| Mandatory | User Management | +| Description | | +| As an admin, I want to be able to add/remove users from access to the tool. I also want to grant different levels of permission to my users with a minimum of: Read Only and Read/Write/Delete/Update so that I can control who is able to do certain things within the tool. | | + +| ID \| Obligation | Title | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------| +| FR-03 \| Mandatory | Use-Case Selection | +| Description | | +| As a user, I want to be able to select, for which Catena-X Use-Case I want to upload data. Based on that selection, I then only want to see relevant information/templates (e.g., semantic models) for that specific Use-Case. If the tool is only built for one use-case, this feature doesn’t apply. | | + +| ID \| Obligation | Title | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------| +| FR-04 \| Mandatory | Understandable Semantic Model Templates | +| Description | | +| As a user, I want to be able to download semantic model templates for the use-case I selected in FR-03 so that I can fill them out with the necessary data. I also want the templates to be understandable for a non-expert in the semantic language so that I can enter the right data in the right fields. | | + +| ID \| Obligation | Title | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------| +| FR-05 \| (Mandatory – See two below) | File Based Upload | +| Description | | +| As a user, I want to be able to upload the filled-out templates from FR-04, so that I can provide data to my partners and so that I can create a “contract offer” with the data attached. | | + +| ID \| Obligation | Title | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------| +| FR-06 \| (Mandatory – See one below) | Guided Text Field Entry | +| Description | | +| As a user, I want to be able to enter the data I need to provide with a guided text field entry e.g. in the case of small amounts of data, or corrections to already provided data. | | + +``` +Note: An upload tool needs to fulfill either FR-05, FR-06 or a similar upload mechanism. +``` + +| ID \| Obligation | Title | +|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------| +| FR-07 \| Mandatory | Access Policy Selection | +| Description | | +| As a user, I want to be able to select which of my partners are allowed to access my data, so that only authorized partners can receive my data. +Remark: Internally, the EDC uses the BPN (CX-0010), but the user should be able to select his business partners based on their company names. For a translation into BPNs the Business Partner Data Pool API (CX-0012) can be used. | | + +| ID \| Obligation | Title | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------| +| FR-08 \| Mandatory | Usage Policy Selection | +| Description | | +| As a user, I want to be able to select under which usage policies my partners are allowed to consume my data, respectively, what my partners are allowed to or obliged to do with my data. Selection of usage policies shall happen in accordance with the Catena-X governance framework for data space operations. | | + +| ID \| Obligation | Title | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| FR-09 \| Mandatory | View uploaded data | +| Description | | +| As a user, I want to be able to view previously uploaded data (FR-05,FR-06). I also want to see who has access to that data (FR-07) and under which conditions I offer the data (FR-08). I want this, so that I can always control if I (or a fellow employee) delivered what our customers requested. | | + +| ID \| Obligation | Title | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------| +| FR-10 \| Mandatory | View data upload history | +| Description | | +| As a user, I don’t only want to see the details of one specific upload, but I want to see a history of all past uploads and then dive into the details of certain uploads, so that I have a transaction log that I could show to my partners to prove, that I uploaded data as agreed. I also want to see changes that were made to uploaded data. | | + +| ID \| Obligation | Title | +|-------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------| +| FR-11 \| Optional | Change uploaded data | +| Description | | +| As a user, I want to be able to change the data that I’ve previously uploaded, so that I can correct a mistake that I’ve previously made. | | + +| ID \| Obligation | Title | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------| +| FR-12 \| Mandatory | Delete uploaded data | +| Description | | +| As a user, I want to be able to delete uploaded data and trigger the deletion of corresponding (meta-)data in all connected systems (e.g. DTR), so that I can e.g. correct mistakes that I’ve previously made or in case I’ve changed my mind about offering certain data to partners. | | + +| ID \| Obligation | Title | +|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------| +| FR-13 \| Optional | Change Access Policy | +| Description | | +| As a user, I want to be able to change the access policy to data that I’ve uploaded, so that I can add access for new partners to already uploaded data. | | + +| ID \| Obligation | Title | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| FR-14 \| Optional | Change Usage Policy | +| Description | | +| As a user, I want to be able to change the usage policy under which I share data with my partner, so that I have the full control over what happens with my data. | | + +``` +Remark: FR-11 & 13,14 are optional, although highly recommended. At minimum, a user needs to be able to delete uploaded data and then make a new upload. +``` + +| ID \| Obligation | Title | +|---------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| +| FR-15 \| Mandatory | Help and Support | +| Description | | +| As a user, I want to have help and support functions in case something isn’t working or I don’t understand what is happening with the tool. | | + +| ID \| Obligation | Title | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------| +| FR-16 \| Mandatory | View status of data offer | +| Description | | +| As a user, I want to see statistics about the consumption of the data that I’ve uploaded, with a minimum of, but not limited to: Who accessed my data; How often was my data accessed; When was the access made So that I can trace what happens with my data. | | + +| ID \| Obligation | Title | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| +| FR-17 \| Mandatory | Logout | +| Description | | +| As a user, I want to log out of the tool, after I’ve finished my task, so that I minimize the risk that an unauthorized colleague accesses the tool on my machine. | | + +| ID \| Obligation | Title | +|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------| +| FR-18 \| Mandatory | Data Validation | +| Description | | +| As a user, I want to have a visual feedback if the data that I’ve uploaded matches with the provided templates. This could include e.g. a validation if all mandatory fields are filled or if the data type matches. If I don’t have a validation, I could send potentially wrong data to my partners, which then can’t process it. | | + +| ID \| Obligation | Title | +|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------| +| FR-19 \| Optional | Append data to an existing upload | +| Description | | +| As a user, I want to be able to append data to an existing “upload” so that I don’t need to re-specify the access and usage policy each and every time I upload something. | | + +``` +It’s difficult to strictly specify the mandatory nonfunctional requirements, as it’s always in the very interest of the data provisioning tool service provider to offer an attractive tool. However, emphasis should be put on three NFRs, as they are especially relevant in the Catena-X network. +``` + +| ID | Title | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +| NFR-01 | Security | +| Description | | +| Companies will provide sensitive and valuable, sometimes even business critical data to partners. Extra measures need to be undertaken to secure both, access to the data as well as to the tool. Furthermore, the endpoint to retrieve the data is exposed to the internet, which means additional thread vectors. | | + +| ID | Title | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| +| NFR-02 | Usability | +| Description | | +| Data upload tools will typically be used not by expert users (e.g. data analysts), but by regular employees of SMEs who are asked to provide data to customers to “stay in business”. The tool needs to take into account, that a typical user has hundreds of tasks and uploading data might just be one of them by e.g. guiding the user through the process, providing additional validation or help/feedback. | | + +| ID | Title | +|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------| +| NFR-03 | Reliability/Availability | +| Description | | +| Catena-X relies on uninterrupted data chains for most of its use-cases. Thus, the data needs to be highly available, as customers follow up processes rely on the availability of data from a provider. | | + +### 2.3 DUTIES OF AN ENABLEMENT SERVICE PROVIDER + +There are various necessary interactions with the services of the core service providers who +operate the core of the network for a data upload tool to work. Those are described in the subsequent chapters. + +Furthermore, besides the need to certify his solution, there are some onboarding activities that an enablement service provider needs to undertake so that he can offer a solution in one of the app stores. For a detailed description please refer to the onboarding information available at the association homepage. + +#### 2.3.1 CREATE SELF-DESCRIPTIONS FOR THE EDC + +Catena-X follows the Gaia-X principles and standards and is committed to +be Gaia-X compliant. This includes issuing so called "self-descriptions" +to participants and services. For Release 3.2 and until further notice, the service +self-descriptions are limited to the "EDC" and Catena-X follows the +trust framework version 10/22 +(http://docs.gaia-x.eu/policy-rules-committee/trust-framework/22.10/). + +Self-Descriptions can be created via the Portal and API, refer to the portal documentation for details. + +An enablement service provider MUST make sure that each connector +that he deploys with the upload tool also gets a valid Self-Description. + +#### 2.3.2 IMPLEMENT SSI SOLUTION + +Starting with Release 3.2, the EDC uses SSI for authentication and authorization. +An upload tool MUST support the correct application of the SSI standards and connect to a wallet. + +#### 2.3.3 REGISTER CONNECTOR AT EDC DISCOVERY SERVICE + +In case the upload tool brings its own connector, it MUST be registered at the EDC discovery service. + +#### 2.3.4 MAKE DIGITAL TWIN REGISTRY DISCOVERABLE + +Note: This chapter only applies if a digital twin registry is required. + +In case the upload tool brings its own digital twin registry, it MUST be discoverable. +To achieve this, the correct entries at the discovery finder and BPN Discovery service MUST be made. + +#### 2.3.5 OPTIONAL: CONNECT TO CX IDP + +One of the value propositions of Catena-X is, that a customer can log in +to the various tools and systems with one single Catena-X identity. To +increase the user experience, data service providers CAN connect the IAM +of the tool with the Catena-X IdP for a SSO integration. + +## 3. REFERENCES + +### 3.1 NORMATIVE REFERENCES + +As long as not specified differently, the latest version of the standard MUST be applied. + +- CX-0013 Identity of Member Companies +- CX-0016 Company Attribute Verification +- CX-0017 Company Role by the Connector +- CX-0018 Eclipse Data Space Connector (EDC) + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +### 3.3 Reference Implementations + +> *This section is non-normative* + +Example: The code found at https://github.com/eclipse-tractusx/dft-frontend in combination with https://github.com/eclipse-tractusx/dft-backend presents a reference implementation that implements this standard. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0007-MinimalDataProviderServicesOffering/assets/CX-0007-picture1.png b/docs/standards/CX-0007-MinimalDataProviderServicesOffering/assets/CX-0007-picture1.png new file mode 100644 index 000000000..75543040d Binary files /dev/null and b/docs/standards/CX-0007-MinimalDataProviderServicesOffering/assets/CX-0007-picture1.png differ diff --git a/docs/standards/CX-0008-RelevantStandardsForConformityAssessments/CX-0008-Relevantstandardsforconformityassessments.md b/docs/standards/CX-0008-RelevantStandardsForConformityAssessments/CX-0008-Relevantstandardsforconformityassessments.md new file mode 100644 index 000000000..79d3acae9 --- /dev/null +++ b/docs/standards/CX-0008-RelevantStandardsForConformityAssessments/CX-0008-Relevantstandardsforconformityassessments.md @@ -0,0 +1,177 @@ + +# CX-0008 Relevant Standards for Conformity Assessments v1.1.0 + +## ABSTRACT + +This standard is relevant for all partners that want to operate within the Catena-X network. +The document defines the internal (e.g. CX Guidelines) and external (e.g. ISO) standards that a partner needs to fulfil before he/she +can offer solutions (services or business applications) in the context of Catena-X. Those standards have been derived from +common incoterms in the automotive industry and present the minimal basis so that software can be used within an automotive +industry enterprise. + +## FOR WHOM IS THE STANDARD DESIGNED + +> *This section is non-normative* + +- Core Service Provider +- Business Application Provider +- Data Provider and Consumer +- Enablement Service Provider +- Onboarding Service Provider + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +> *This section is non-normative* + +The requirement for ISO 9001 certification, which was required in previous versions, +meant a high effort for the affected companies and an improper focus for IT-oriented companies like e.g. IT outfitters. +ISO 27001 and TISAX Infosec are considered suitable alternatives and therefore companies can now certify to ISO 27001 and/or TISAX Infosec and/or ISO 9001 alternatively. +Furthermore, the certification period for a first certification is extended from 12 months to 24 months. + +The Business Network Provider role has been replaced with the Onboarding Service Provider role. + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This document is relevant for all partners that want to operate within +the Catena-X network. More specifically, this document is intended for +the following roles + +- Core Service Provider +- Business Application Provider +- Data Provider and Consumer +- Enablement Service Provider +- Onboarding Service Provider + +### 1.2 CONTEXT + +> *This section is non-normative* + +This document defines the internal (e.g. CX Guidelines) and external (e.g. ISO) +standards that a partner needs to fulfil before he/she can offer +solutions (services or business apps) in the context of Catena-X. Those +standards have been derived from common incoterms in the automotive +industry and present the minimal basis so that software can be used +within an automotive industry enterprise. + +Requesting certain standards from partners secures that all customers +that use solutions (services or business apps) are guaranteed a certain +level of professionality, security, and trust. + +Conformity with the basic standards for the roles listed above is not +optional. Without a successful conformity assessment, the onboarding +process cannot be completed. It's important to mention, that +additionally to the conformity assessment of the partner itself, the +solutions will later in the process also need to demonstrate conformity +with e.g. use-case specific standards. However, this is not covered here +but in the standards for each use-case. This document only deals with +the use-case agnostic standards on a partner level. + +If you are unsure about your company's role or if you need a general +introduction to conformity assessment within Catena-X, please read the +Operating Whitepaper. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +Depending on the role, the partner collects the self-assessments for +internal and/or certificates for external standards and sends them to +the responsible CAB. The responsible CABs can be found on the homepage +of the association: [www.catena-x.net](http://www.catena-x.net). + +The partner can finalize the onboarding only after successful +verification of conformity. + +## 2 RELEVANT STANDARDS FOR CONFORMITY ASSESSMENT + +> *This section is normative* + +The following table lists the relevant internal and external standards +per role and describes the necessary tasks to proof conformity with that +standard. Details about each standard can be found on the homepage of +the association: [www.catena-x.net](http://www.catena-x.net). + +Note: Until further notice, partners will need to conduct an internal +audit/self-assessment and validate that they fulfil the respective +Catena-x internal standards. For Catena-X internal standards, a template +for a self-assessment will be provided. + +The CABs -- acting on behalf of the association -- can in specific cases +allow deviation from the standards and still issue a certificate of +conformity. + +| ID \| Obligation \| Role | Standard Name | +|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------| +| 01 \| Mandatory \| Core Service Provider, Enablement Service Provider, Business Application Provider, Onboarding Service Provider | ISO 9001 – Quality Management Systems or ISO 27001 – Information Security (with regard to the scope of proposed services) or TISAX Level 1 | +| Description | | +| The respective roles must provide evidence that they are certified or in the process of being (re)certified to one of these standards at the time of the assessment. If they fail to achieve a (re-)certification within twelve/twenty-four months – starting from the date of an initial application for Catena-X Certification - , they will be offboarded from Catena-X immediately. The first certification period is twenty-four months, and the following certification periods are twelve months. | | + +| ID \| Obligation \| Role | Standard Name | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------| +| 02 \| Recommended \| Core Service Provider, Enablement Service Provider, Business Application Provider, Onboarding Service Provider | ISO27001 – Information Security or TISAX Level 1 or ISO 9001 - Quality Management Systems | +| Description | | +| The respective roles need to provide a proof that they – at the time of the assessment – are ISO27001 or TISAX Level 1 or ISO 9001 certified or are in the process of receiving a (re-)certification. If they fail to achieve a (re-)certification within twelve/twenty-four months – starting from the date of an initial application for Catena-X Certification - , they will be offboarded from Catena-X immediately. The first certification period is twenty-four months, and the following certification periods are twelve months. To meet this requirement, a second certification must be demonstrated in addition to the certification referenced in obligation 01. | | + +| ID \| Obligation \| Role | Standard Name | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------| +| 03 \| Recommended \| Core Service Provider, Enablement Service Provider, Business Application Provider, Onboarding Service Provider | ISO270018 – Information Security | +| Description | | +| The respective roles need to provide a proof that they – at the time of the assessment – are ISO27018 certified or are in the process of receiving a (re-)certification. If they fail to achieve a (re-)certification within twelve/twenty-four months – starting from the date of an initial application for Catena-X Certification - , they will be offboarded from Catena-X immediately. The first certification period is twenty-four months, and the following certification periods are twelve months. | | + +| ID \| Obligation \| Role | Standard Name | +|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| +| 04 \| Recommended \| Core Service Provider, Enablement Service Provider, Business Application Provider, Onboarding Service Provider | ISO20000-1 – IT Service Management | +| Description | | +| The respective roles need to provide a proof that they – at the time of the assessment – are ISO20000-1 certified or are in the process of receiving a (re-)certification. If they fail to achieve a (re-)certification within twelve/twenty-four months – starting from the date of an initial application for Catena-X Certification - , they will be offboarded from Catena-X immediately. The first certification period is twenty-four months, and the following certification periods are twelve months. | | + +| ID \| Obligation \| Role | Standard Name | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------| +| 05 \| Recommended \| Core Service Provider, Enablement Service Provider, Business Application Provider, Onboarding Service Provider | ISO22301 – Business Continuity Management | +| Description | | +| The respective roles need to provide a proof that they – at the time of the assessment – are ISO22310 certified or are in the process of receiving a (re-)certification. If they fail to achieve a (re-)certification within twelve/twenty-four months – starting from the date of an initial application for Catena-X Certification - , they will be offboarded from Catena-X immediately. The first certification period is twenty-four months, and the following certification periods are twelve months. | | + +### 2.1 OUTLOOK + +The following guidelines aren't published at the time of standard +creation. As soon as they become available, there will be a transition +period until the guidelines become mandatory. + +| ID \| Obligation \| Role | Title | +|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| +| 06 \| Mandatory \| Core Service Provider, Enablement Service Provider, Business Application Provider, Onboarding Service Provider | Catena-X internal guideline - Guideline Data Sovereignty. | +| Description | | +| Not available yet. The respective roles need to conduct an internal audit and provide a self-assessment, that they follow the Guideline Data Sovereignty. | | + +| ID \| Obligation \| Role | Title | +|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------| +| 07 \| Mandatory \| Core Service Provider, Enablement Service Provider, Business Application Provider, Onboarding Service Provider | Catena-X internal guideline - Leitlinie Informationssicherheit / Guideline Information Security | +| Description | | +| Not available yet. The respective roles need to conduct an internal audit and provide a self-assessment, that they follow the Leitlinie Informationssicherheit / Guideline Information Security. | | + +| ID \| Obligation \| Role | Title | +|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| +| 08 \| Mandatory \| Core Service Provider, Enablement Service Provider, Business Application Provider, Onboarding Service Provider | Catena-X internal guideline - Leitlinie Datenverarbeitung / Guideline Data Processing | +| Description | | +| Not available yet. The respective roles need to conduct an internal audit and provide a self-assessment, that they follow the Leitlinie Datenverarbeitung / Guideline Data Processing. | | + +## REVISIONS & UPDATE + +- v1.1.0 Added ISO 27001 and/or TISAX Level 1 as alternative to ISO 9001 + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0009-CXRegistrationAPI/CX-0009-CXRegistrationAPI.md b/docs/standards/CX-0009-CXRegistrationAPI/CX-0009-CXRegistrationAPI.md new file mode 100644 index 000000000..2c51e0d33 --- /dev/null +++ b/docs/standards/CX-0009-CXRegistrationAPI/CX-0009-CXRegistrationAPI.md @@ -0,0 +1,724 @@ +# CX-0009 CX Registration API v2.0.0 + +## CAMPARISON TO THE LAST VERSION + +| Version | Change by | Change Details | +|---------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 2.0.0 | Julia Jeroch | Update of the endpoint details which MUST/SHOULD get followed by the Core Service Provider and/or Onboarding service provider. Endpoint path as well as request/response body. | + +## ABSTRACT + +To become a participant of Catena-X, each applicant must go through a +registration process. Registration is a mandatory requirement for all +further activities within the Catena-X network. The registration +process, along with other services, provide the foundation of trust for +the Catena-X network. + +The Registration & Administration Service describes the endpoints that are needed for +the registration process. + +## 1. Introduction + +To become a participant of Catena-X, each applicant must go through a +registration process. Registration is a mandatory requirement for all +further activities within the Catena-X network. The registration +process, along with other services, provide the foundation of trust for +the Catena-X network. + +### 1.1 Audience & Scope + +> *This section is non-normative* + +This standard is relevant for the following roles: + +- Core Service Provider +- Onboarding Service Provider (for reference) + +### 1.2 Context + +> *This section is non-normative* + +The registration API is used as part of the registration process. + +### 1.3 Architecture Overview + +> *This section is non-normative* + +A core service provider operates among other things a registration +frontend through which a registering company can enter its data. In the +future, the registration service may be accessed remotely, for example +by onboarding service provider, so the API needs to be standardized. + +![CX-0009-architecture-overview1.jpg](./assets/CX-0009-architecture-overview1.jpg) + +### 1.4 Conformance + +As well as sections marked as non-normative, all authoring guidelines, +diagrams, examples, and notes in this specification are non-normative. +Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, +SHOULD and SHOULD NOT in this document are to be interpreted as +described in [BCP +14](https://datatracker.ietf.org/doc/html/bcp14) \[[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)\] +\[[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)\] when, and +only when, they appear in all capitals, as shown here. + +### 1.5 Proof of conformity + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they are +conform with the Catena-X standards. To validate that the standards are +applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +Core service providers implementing their own registration solution MUST +proof their conformity by providing: + +- An openAPI specification of the endpoints described + +### 1.6 Terminology + +> *This section is non-normative* + +**Application Programming Interface (API)** + +An application programming interface (API) is a way for two or more +computer programs to communicate with each other. + +Additional terminology used in this standard can be looked up in the +glossary on the association homepage. + +## 2. Catena-X Registration API + +### 2.1 Preconditions and dependencies + +The registration API is exposed to the Internet. + +### 2.2 API Specification + +### 2.2.1 API-Endpoints - Core Service Provider + +The Core Service Provider MUST implement the following endpoints -- in focus +are the API business logic / content and structure, the path name might change / be +different but the business logic behind as well as the attributes must +be followed. Details to the respective MUST and SHOULD statements may be found below. + +>> Note functional description and standard definition of the CSP role are defined inside the standard CX-0006-RegistrationAndInitialOnboarding. + +#### 2.2.1.1 Enter / verify company data + +**Endpoint:** `/api/registration/legalEntityAddress/{bpn}` + +**Method:** `GET` + +**Description & Information:** +Please note - this endpoint is currently only Core Service Provider relevant. The Core Service Provider **MUST** be able to pre-fill the company address data if the requester company has a BPN. The endpoint path **MUST NOT** be followed as long as all validations and processes are implemente + +**Request body** + +```json +n/a +``` + +**Response body** + +```json +{ + "version": { + "characterSet": { + "technicalKey": "string", + "name": "string" + }, + "language": { + "technicalKey": "string", + "name": "string" + } + }, + "careOf": "string", + "contexts": [ + "string" + ], + "country": { + "technicalKey": "string", + "name": "string" + }, + "administrativeAreas": [ + { + "value": "string", + "shortName": "string", + "fipsCode": "string", + "type": { + "technicalKey": "string", + "name": "string" + }, + "language": { + "technicalKey": "string", + "name": "string" + } + } + ], + "postCodes": [ + { + "value": "string", + "type": { + "technicalKey": "string", + "name": "string" + } + } + ], + "localities": [ + { + "value": "string", + "shortName": "string", + "type": { + "technicalKey": "string", + "name": "string" + }, + "language": { + "technicalKey": "string", + "name": "string" + } + } + ], + "thoroughfares": [ + { + "value": "string", + "name": "string", + "shortName": "string", + "number": "string", + "direction": "string", + "type": { + "technicalKey": "string", + "name": "string" + }, + "language": { + "technicalKey": "string", + "name": "string" + } + } + ], + "premises": [ + { + "value": "string", + "shortName": "string", + "number": "string", + "type": { + "technicalKey": "string", + "name": "string" + }, + "language": { + "technicalKey": "string", + "name": "string" + } + } + ], + "postalDeliveryPoints": [ + { + "value": "string", + "shortName": "string", + "number": "string", + "type": { + "technicalKey": "string", + "name": "string" + }, + "language": { + "technicalKey": "string", + "name": "string" + } + } + ], + "geographicCoordinates": { + "longitude": 0, + "latitude": 0, + "altitude": 0 + }, + "types": [ + { + "technicalKey": "string", + "name": "string" + } + ] +} +``` + +--- + +**Endpoint:** `/api/registration/application/{applicationId}/companyDetailsWithAddress` + +**Method:** `GET` + +**Description & Information:** +The Core Service Provider **MUST** provide the GET /\{applicationId\}/companyDetailsWithAddress endpoint for a standardized way to receive the registration party data. + +**Request body** + +```json +n/a content inside the path +``` + +**Response body** + +```json +{ + "name": "string", + "city": "string", + "streetName": "string", + "countryAlpha2Code": "string", + "bpn": "string", + "shortName": "string", + "region": "string", + "streetAdditional": "string", + "streetNumber": "string", + "zipCode": "string", + "uniqueIds": [ + { + "type": "COMMERCIAL_REG_NUMBER", + "value": "string" + } + ], + "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" +} +``` + +--- + +**Endpoint:** `/api/registration/company/country/{alpha2Code}/uniqueidentifiers` + +**Method:** `GET` + +**Description & Information:** +The Core Service Provider **CAN** offer a GET /uniqueidentifiers endpoint to provide supported unique identifier based on the company lega address country alpha2Code. + +**Request body** + +```json +n/a content inside the path +``` + +**Response body** + +```json +[ + { + "id": 0, + "label": "COMMERCIAL_REG_NUMBER" + } +] +``` + +--- + +**Endpoint:** `/api/registration/application/{applicationId}/companyDetailsWithAddress` + +**Method:** `POST` + +**Description & Information:** +The Core Service Provider **MUST** provide the POST /\{applicationId\}/companyDetailsWithAddress endpoint for a standardized way to store/post the registration party data. + +**Request body** + +```json +{ + "name": "string", + "city": "string", + "streetName": "string", + "countryAlpha2Code": "string", + "bpn": "string", + "shortName": "string", + "region": "string", + "streetAdditional": "string", + "streetNumber": "string", + "zipCode": "string", + "uniqueIds": [ + { + "type": "COMMERCIAL_REG_NUMBER", + "value": "string" + } + ], + "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" +} +``` + +**Response body** + +```json +success/error +``` + +#### 2.2.1.2 Company roles and consent + +**Endpoint:** `/api/registration/company/companyRoles` + +**Method:** `GET` + +**Description & Information:** +The Core Service Provider **MUST** implement the GET /companyRoles endpoint. + +**Request body** + +```json +n/a content inside the path +``` + +**Response body** + +```json +[ + { + "companyRole": "string", + "roleDescription": "string" + } +] +``` + +--- + +**Endpoint:** `/api/registration/companyRoleAgreementData` + +**Method:** `GET` + +**Description & Information:** +The Core Service Provider **MUST** implement the GET /companyRoleAgreementData endpoint. + +**Request body** + +```json +n/a content inside the path +``` + +**Response body** + +```json +{ + "companyRoles": [ + { + "companyRole": "ACTIVE_PARTICIPANT", + "descriptions": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "agreementIds": [ + "3fa85f64-5717-4562-b3fc-2c963f66afa6" + ] + } + ], + "agreements": [ + { + "agreementId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "name": "string", + "agreementLink": "string", + "documentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + } + ] +} +``` + +--- + +**Endpoint:** `/api/registration/application/{applicationId}/companyRoleAgreementConsents` + +**Method:** `POST` + +**Description & Information:** +The Core Service Provider **MUST** implement the GET /companyRoleAgreementConsents endpoint. + +**Request body** + +```json +{ + "companyRoles": [ + "ACTIVE_PARTICIPANT" + ], + "agreements": [ + { + "agreementId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "consentStatus": "ACTIVE" + } + ] +} +``` + +**Response body** + +```json +success/error +``` + +#### 2.2.1.3 Registration relevant documents + +**Endpoint:** `/api/registration/application/{applicationId}/documentType/{documentTypeId}/documents` + +**Method:** `GET` + +**Description & Information:** +The Core Service Provider **SHOULD** implement the GET /\{documentTypeId\}/documents endpoint. + +--- + +**Endpoint:** `/api/registration/application/{applicationId}/documentType/{documentTypeId}/documents` + +**Method:** `POST` + +**Description & Information:** +The Core Service Provider **SHOULD** implement the POST /\{documentTypeId\}/documents endpoint. Depending on the Core Service Provider implemented registration process authentication methods, the document endpoint might change within the endpoint path or business logic. + +--- + +**Endpoint:** `/api/registration/documents/{documentId}` + +**Method:** `DELETE` + +**Description & Information:** +The Core Service Provider **SHOULD** implement the DELETE /\{documentTypeId\}/documents endpoint to enable the onboarding customer to delete own previous uploaded document again. Important are audit relevant processes. The Core Service Provider **MUST** ensure that audit guidelines are not violated. + +--- + +**Endpoint:** `/api/registration/documents/{documentId}` + +**Method:** `GET` + +**Description & Information:** +The Core Service Provider **MUST** support to display the user company loaded documents. The endpoint path might change but the Core Service Provider **MUST** ensure that validations are implemeneted (e.g. the company user can not access uploaded documents of a second registration company) + +#### 2.2.1.4 Verify and submit registration + +**Endpoint:** `/api/registration/application/{applicationID}/registrationData` + +**Method:** `GET` + +**Description & Information:** +The Core Service Provider **MUST** support a GET /\{applicationID\}/registrationData endpooint with the reference implemented properties/attributes. This ensures that the company registrationData can be viewed in a standardized model. + +**Request body** + +```json +{ + "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "name": "string", + "bpn": "string", + "shortName": "string", + "city": "string", + "region": "string", + "streetAdditional": "string", + "streetName": "string", + "streetNumber": "string", + "zipCode": "string", + "countryAlpha2Code": "string", + "companyRoles": [ + "ACTIVE_PARTICIPANT" + ], + "agreements": [ + { + "agreementId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "consentStatus": "ACTIVE" + } + ], + "documents": [ + { + "documentName": "string" + } + ], + "uniqueIds": [ + { + "type": "COMMERCIAL_REG_NUMBER", + "value": "string" + } + ] +} +``` + +**Response body** + +```json +success/error +``` + +--- + +**Endpoint:** `/api/registration/application/{applicationID}/submitregistration` + +**Method:** `POST` + +**Description & Information:** +... + +**Request body** + +```json +n/a +``` + +**Response body** + +```json +success/error +``` + +#### 2.2.1.5 Registration Application Verification + +Auto Workflow as per the process description: https://github.com/eclipse-tractusx/portal-assets/blob/main/developer/01.%20Onboarding/03.%20Registration%20Approval/03.%20Registration%20Approval%20Process.md + +- POST + /api/administration/registration/application/\{applicationId\}/approve + Please note - this endpoint is currently only Core Service Provider relevant. The Core Service Provider **MUST** be able to approve (with message, backend business logic and email information) a registration request. The endpoint path **MUST NOT** be followed as long as all validations and processes are implemented. + +- POST + /api/administration/registration/application/\{applicationId\}/decline + Please note - this endpoint is currently only Core Service Provider relevant. The Core Service Provider **MUST** be able to decline (with message and email information) a registration request. The endpoint path **MUST NOT** be followed as long as all validations and processes are implemented. + +- POST /api/administration/registration/application/clearinghouse + Please note - this endpoint is currently only Core Service Provider relevant. The Core Service Provider **MUST** be able to trigger the CH trust anchor. The endpoint path **MUST NOT** be followed, but the endpoint business logic and request body must be followed to allow a standardized interface with the GXCH. + +- POST /api/administration/registration/application/\{applicationId\}/retrigger-clearinghouse + Please note - this endpoint is currently only Core Service Provider relevant. The Core Service Provider **MUST** be able to retrigger/overwrite the CH decision if necessary. The endpoint path **MUST NOT** be followed, but the endpoint business logic must be followed to allow a standardized interface with the GXCH. + +- POST /api/administration/registration/application/\{applicationId\}/trigger-identity-wallet + +- POST /api/administration/registration/application/\{applicationId\}/trigger-bpn + +- POST /api/administration/registration/application/clearinghouse/selfDescription + Please note - this endpoint is currently only Core Service Provider relevant. The Core Service Provider **MUST** support the endpoint - path can change but endpoint structure must be followed + +**Request body** + +```json + { + "externalId": "uuid", + "status": "Confirm", + "message": "string", + "selfDescriptionDocument": "string" + } +``` + +#### 2.2.2 PartnerNetwork enablement + +- CSP **MUST** provide OSPs a submit partnerRegistration endpoint POST /api/administration/registration/Network/partnerRegistration/submit + Onboarding Service provider. The endpoint path might be different; but the endpoint structure and business logic needs to follow the standard defined below. + +**Request body/Submit body** + +```json + { + "externalId": "id - unique per OSP", + "name": "string", + "bpn": "string", + "city": "string", + "streetName": "string", + "countryAlpha2Code": "string", + "region": "string", + "streetNumber": "string", + "zipCode": "string", + "uniqueIds": [ + { + "type": "COMMERCIAL_REG_NUMBER", + "value": "string" + } + ], + "userDetails": [ + { + "identityProviderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "providerId": "string", + "username": "string", + "firstName": "string", + "lastName": "string", + "email": "string" + } + ], + "companyRoles": [ + "ACTIVE_PARTICIPANT" + ] + } +``` + +- CSP **MUST** provide OSPs a endpoint to configure and view the OSP owned callback URL GET & POST /api/administration/RegistrationStatus/callback + +**Body** + +```json + { + "callbackUrl": "string", + "authUrl": "string", + "clientId": "string", + "clientSecret": "string" + } +``` + +#### 2.2.2.1 API-Endpoints - Onboarding Service Provider + +The Onboarding Service Provider MUST implement the following endpoints -- in focus +are the API business logic / content and structure, the path name might change / be +different but the business logic behind as well as the attributes must +be applied/followed. Details to the respective MUST and SHOULD statements may be found below. + +>> Note functional details and collaboration between OSP and CSP can get found inside the standard CX-0006-RegistrationAndInitialOnboarding. + +- Submit partnerRegistration + Onboarding Service provider MUST be able to submit 3rd party registration to the CSP provided endpoint POST /api/administration/registration/Network/partnerRegistration + +**Request body/Submit body** + +```json + { + "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "name": "string", + "bpn": "string", + "city": "string", + "streetName": "string", + "countryAlpha2Code": "string", + "region": "string", + "streetNumber": "string", + "zipCode": "string", + "uniqueIds": [ + { + "type": "COMMERCIAL_REG_NUMBER", + "value": "string" + } + ], + "userDetails": [ + { + "identityProviderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "providerId": "string", + "username": "string", + "firstName": "string", + "lastName": "string", + "email": "string" + } + ], + "companyRoles": [ + "ACTIVE_PARTICIPANT" + ] + } +``` + +#### 2.2.3 Available Data Types + +The registration API MUST use JSON as the payload transported via HTTP. + +#### 2.2.4 API resources & endpoints + +The HTTP endpoints introduced in this standard MUST implement +authentication and authorization. + +#### 2.2.5 Error Handling + +HTTP standard response codes MUST be used. + +##### 2.2.5.1 Error Messages & Explanation + +The following http response codes MUST be defined for HTTP POST +endpoint: + +| Code | Description | +|-------------|-------------------------------------------------------| +| 201 | Registration message was received successfully | +| 400 | Request body was malformed | +| 401 | Not authorized | +| 403 | Forbidden | +| 405 | Method not allowed | +| 409 | Error | + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0009-CXRegistrationAPI/assets/CX-0009-architecture-overview1.jpg b/docs/standards/CX-0009-CXRegistrationAPI/assets/CX-0009-architecture-overview1.jpg new file mode 100644 index 000000000..381074a5d Binary files /dev/null and b/docs/standards/CX-0009-CXRegistrationAPI/assets/CX-0009-architecture-overview1.jpg differ diff --git a/docs/standards/CX-0010-BusinessPartnerNumber/CX-0010-BusinessPartnerNumber.md b/docs/standards/CX-0010-BusinessPartnerNumber/CX-0010-BusinessPartnerNumber.md new file mode 100644 index 000000000..ad14727b9 --- /dev/null +++ b/docs/standards/CX-0010-BusinessPartnerNumber/CX-0010-BusinessPartnerNumber.md @@ -0,0 +1,213 @@ + +# CX-0010 Business Partner Number v2.0.0 + +## ABSTRACT + +The Business Partner Data Management (BPDM) is a distributed service-based system, composed of a set of dedicated services, that simultaneously serve multiple stakeholders. It is based on a central data pool of business partners, which is consistent with the overall design principles of Catena-X. The main target is to create business partner data records (such as customer/supplier) with a high quality and currentness, to provide other processes with these data. This results in less rework and adjustment due to better master data quality which ultimately leads to an overall cost reduction for participating companies. Additionally, Value Added Services shall be offered to enrich those business partner data sets even further and give additional information or warnings about the business partners. Getting a 360° view on your business partners also helps with reducing costs and achieving process excellence because better decisions can be made. + +The Business Partner Number (BPN) is a unique identifier that is assigned to each business partner. The following represents the technical documentation for the Business Partner Number in the platform capability Business Partner Data Management. This standard documentation defines the structure and creation of a Business Partner Number. + +## 1. INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following audience: + +- Core Service Provider +- Onboarding Service Provider +- Business Application Provider +- Data Provider and Consumer + +This document focuses on the Business Partner Number (BPN) and its issuing agency that is part of the Business Partner Data Management (BPDM) described on the [BPDM Catena-X Website](https://catena-x.net/en/offers/bpdm).It is relevant for core service providers who want to provide services for retrieving a cleansed, high-quality business partner data record (Golden Record) for a given Business Partner Number. It is also relevant for onboarding service providers, business application providers as well as data providers and consumers who want to use such services. + +The BPN is the one unique identifier for business partners in the network. To maintain the issuing agency, core service providers especially need to get an understanding on the syntax of the BPN, the versions, and relations. In addition to that the lifecycle of a BPN is important. + +Not in scope is the way of how business partner data records can be shared to create a Golden Record. There is a separate standard for this: Business Partner Gate API. + +Not in scope is the overall Business Partner Pool with all Golden Records within Catena-X and the way of how the Golden Records can be retrieved. There is a separate standard for this: Business Partner Pool API. + +Not in scope are the requirements of cleansing and enriching the business partner data records with the aim to create a Golden Record. A separate standard is being prepared but will not be available simultaneously with this standard. + +You can find the other standards in the standard library of Catena-X: [https://catena-x.net/de/standard-library](https://catena-x.net/de/standard-library). + +### 1.2 CONTEXT + +> *This section is non-normative* + +It is not only with the founding of various industry networks (such as Catena-X) that the requirements increase to establish data standards for the entire automotive value chain and to promote the industry-wide, international data exchange. For the networking of OEMs, suppliers, customers, and industrial partners, it is essential to define and introduce a cross-industry standard for identifying business partners to map the entire supply chain in a sustainable manner. + +### 1.3 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD and SHOULD NOT in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) [[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)] [[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)] when, and only when, they appear in all capitals, as shown here. + +### 1.4 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To proof conformity with this standard, a self-audited, stated and signed document that the syntax of the BPN is established must be provided. + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +### 1.5.1 General + +**Golden Record:** Golden Record defines a business partner data record which successfully passed a set of predefined quality rules. These rules qualified the data record into a harmonized, standardized, and semantically unified data structure which is defined by Catena-X. The Golden Record status is a prerequisite for each BP data record to receive a valid BPN. + +**Sharing Member:** A sharing member is a BPDM member who shares the Business Partner data of his own system. + +### 1.5.2 Business Partner + +![Business Partner](./assets/business-partner.png) + +In general, a business partner is any entity (such as a customer, a supplier, an employee, or a service provider) that does business with another entity. + +In Catena-X, a business partner is an organization (and not a natural person) or one of its substructures (such as an enterprise or company, university, association, etc.) that acts as unique partner within the automotive supply chain – either in the role of a direct participant, or a consultant, or a non-production-material (NPM) supplier. + +Catena-X distinguishes between three business partner types to represent an organization with its substructures relevant for the automotive supply chain: legal entity, site, and address (see detailed definitions). + +### 1.5.3 Legal Entity + +![Legal Entity](./assets/legal-entity.png) + +In general, a legal entity is a juridical person that has legal rights and duties related to contracts, agreements, and obligations. The term especially applies to any kind of organization (such as an enterprise or company, university, association, etc.) established under the law applicable to a country. + +In Catena-X, a legal entity is a type of business partner representing a legally registered organization with its official registration information, such as legal name (including legal form, if registered), legal address and tax number. + +A legal entity has exactly one legal address, but it is possible to specify additional addresses that a legal entity owns. Thus, at least one address is assigned to a legal entity. A legal entity can own sites. Thus, many or no sites are assigned to a legal entity.  A legal entity is uniquely identified by the BPNL. + +A BPNL represents and uniquely identifies a legal entity, which is defined by its legal name (including legal form, if registered), legal address and tax number. + +### 1.5.4 Site + +![Site](./assets/site.png) + +In general, a site is a delimited geographical area in which an organization (such as an enterprise or company, university, association, etc.) conducts business. + +In Catena-X, a site is a type of business partner representing a physical location or area owned by a legal entity, where a production plant, a warehouse, or an office building is located. + +A site is owned by a legal entity. Thus, exactly one legal entity is assigned to a site. A site has exactly one main address, but it is possible to specify additional addresses (such as different gates), that belong to a site. Thus, at least one address is assigned to a site. A site can only be uploaded and modified by the owner (the legal entity), because only the owner knows which addresses belong to which site. A site is uniquely identified by the BPNS. + +A BPNS represents and uniquely identifies a site, which is where for example a production plant, a warehouse, or an office building is located. + +### 1.5.5 Address + +![Address](./assets/address.png) + +In general, an address is a collection of information to describe a physical location, using a street name with a house number and/or a post office box as reference. In addition, an address consists of several postal attributes, such as country, region (state), county, township, city, district, or postal code, which help deliver mail. + +In Catena-X, an address is a type of business partner representing the legal address of a legal entity, and/or the main address of a site, or any additional address of a legal entity or site (such as different gates). + +An address is owned by a legal entity. Thus, exactly one legal entity is assigned to an address. An address can belong to a site. Thus, one or no site is assigned to an address. An address is uniquely identified by the BPNA. + +A BPNA represents and uniquely identifies an address, which can be the legal address of a legal entity, and/or the main address of a site, or any additional address of a legal entity or site (such as different gates). + +It is important to note that only the BPNL must be used to uniquely identify a legal entity. Even in the case that the BPNA represents the legal address of the legal entity, it shall not be used to uniquely identify the legal entity. + +# 2 BUSINESS PARTNER NUMBER + +## 2.1 BPN + +The BPN is a unique, unchangeable identifier for business partners from foundation to closure, regardless of the different business relationships / structures between or within the business partners or company locations. It MUST follow the defined syntax and structure: + +| **Prefix** | **Classification** | **Identifier** | **Check Digit** | +| --- | --- | --- | --- | +| 3-digit | 1-digit | 10-digit | 2-digit | +| Issuing Agency Code according to ISO/IEC 15459 e.g. BPN | L = Legal Entity S = Site A = Address | alphanumerical | 2-digit verification algorithm according to ISO 7064 MOD 1271-36 | + +Further information: + +The following input or reading aid SHOULD be used for human readable representation of the BPN: BPNL 1234 5678 90ZZ + +## 2.2 Lifecycle + +The BPNs of a legal entity (BPNL), a site (BPNS), or an address (BPNA) have an own life cycle, depending on the respective status of the legal entity, the site, or the address in the real world. + +Each BPNL, BPNS and BPNA data record contains a start and end date which defines the validity duration of the related data record. + +They MUST follow the status definitions + +- active +- inactive + +## 2.3 Relations + +There are relations between a legal entity (BPNL), its sites (BPNS), and its addresses (BPNA). Each organization in the real world (such as an enterprise or company, university, association, etc.) is represented by one legal entity. Each legal entity MUST have at least one address which is its legal address. If a site exists it MUST be associated exactly to one legal entity. A legal entity MAY have multiple sites. Each site MUST have at least one address which is its main address. See example under 2.4 for explanation. + +## 2.4 Examples + +Exemplary BPN: BPNL1234567890ZZ + +**BPN:** is used here as a placeholder for the issuing agency according to IDO/IEC 15459. + +**L:** identifies the legal entity of the business partner + +**ZZ** : is the individual check digit, which is formed according to ISO 7064. + +Example *ABC Inc.* with its relatedsubstructures: +![ABC_INC](./assets/abc-inc.png) + +## 2.5 Out of Scope + +For the following entities a BPN SHALL NOT be issued: + +- natural persons (such as employees) who act for a legal entity and not as own business partners +- forms of freight forwarding (such as c/o addresses) +- elements of (legal) hierarchies (such as business global ultimate) +- internal unloading points (logistically) + +## 2.6 Issuing Agency + +The issuing agency is a technical mechanism that centrally assigns BPNs to ensure the highest data quality in the data sharing process. Catena-X e.V. issues a license through which an operating company MUST operate the mechanism to issue further BPNs. BPNs are issued for legal entities, sites, and addresses. The issuing agency is specified in the prefix of the BPN according to ISO/IEC 15459. + +### 2.6.1 Building Block View + +The BPDM API receives cleaned data sets from the SaaS Adapter. BPNs are issued centrally. For this purpose, the BPN is assigned on the BPDM side subsequently to the API and the SaaS adapter. The updated data objects are then mirrored back to the other services. + +![Building Block View](./assets/building-block-view.png) + +### 2.6.2 Run Time View + +This runtime view illustrates the data sharing mechanism between a sharing member, the SaaS component, including the BPN issuing by the BPN Generator. An actor can be any sharing member that shares data with Catena-X. The new data object is transferred from the enterprise layer of the sharing member to the Catena-X gate. This gate interacts with the API of the SaaS component. The SaaS component fetches information about their synchronization and receives the new data objects in response. The BPN generator issues a BPN, and the data objects are changed accordingly. The SaaS adapter polls the changed data. The updated data objects are then available via standardized APIs. + +![Run Time View](./assets/run-time-view.png) + +# 3 REFERENCES + +## 3.1 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +[BPDM Catena-X Website](https://catena-x.net/en/offers/bpdm) + +## 3.2 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +[Business Partner Pool API](https://github.com/eclipse-tractusx/bpdm/tree/main/bpdm-pool-api/src/main/kotlin/org/eclipse/tractusx/bpdm/pool/api) + +[Business Partner Gate API](https://github.com/eclipse-tractusx/bpdm/tree/main/bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api) + +# ANNEXES + +## FIGURES + +> *This section is non-normative* + +Intentionally left blank. + +## TABLES + +> *This section is non-normative* + +Intentionally left blank. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0010-BusinessPartnerNumber/assets/abc-inc.png b/docs/standards/CX-0010-BusinessPartnerNumber/assets/abc-inc.png new file mode 100644 index 000000000..8ae01690d Binary files /dev/null and b/docs/standards/CX-0010-BusinessPartnerNumber/assets/abc-inc.png differ diff --git a/docs/standards/CX-0010-BusinessPartnerNumber/assets/address.png b/docs/standards/CX-0010-BusinessPartnerNumber/assets/address.png new file mode 100644 index 000000000..e1646ad07 Binary files /dev/null and b/docs/standards/CX-0010-BusinessPartnerNumber/assets/address.png differ diff --git a/docs/standards/CX-0010-BusinessPartnerNumber/assets/building-block-view.png b/docs/standards/CX-0010-BusinessPartnerNumber/assets/building-block-view.png new file mode 100644 index 000000000..2d9fb9ffa Binary files /dev/null and b/docs/standards/CX-0010-BusinessPartnerNumber/assets/building-block-view.png differ diff --git a/docs/standards/CX-0010-BusinessPartnerNumber/assets/business-partner.png b/docs/standards/CX-0010-BusinessPartnerNumber/assets/business-partner.png new file mode 100644 index 000000000..557e3e5db Binary files /dev/null and b/docs/standards/CX-0010-BusinessPartnerNumber/assets/business-partner.png differ diff --git a/docs/standards/CX-0010-BusinessPartnerNumber/assets/legal-entity.png b/docs/standards/CX-0010-BusinessPartnerNumber/assets/legal-entity.png new file mode 100644 index 000000000..a033bc8d2 Binary files /dev/null and b/docs/standards/CX-0010-BusinessPartnerNumber/assets/legal-entity.png differ diff --git a/docs/standards/CX-0010-BusinessPartnerNumber/assets/run-time-view.png b/docs/standards/CX-0010-BusinessPartnerNumber/assets/run-time-view.png new file mode 100644 index 000000000..6436c64da Binary files /dev/null and b/docs/standards/CX-0010-BusinessPartnerNumber/assets/run-time-view.png differ diff --git a/docs/standards/CX-0010-BusinessPartnerNumber/assets/site.png b/docs/standards/CX-0010-BusinessPartnerNumber/assets/site.png new file mode 100644 index 000000000..950840ff3 Binary files /dev/null and b/docs/standards/CX-0010-BusinessPartnerNumber/assets/site.png differ diff --git a/docs/standards/CX-0011-IssuingAgency/CX-0011-IssuingAgency.md b/docs/standards/CX-0011-IssuingAgency/CX-0011-IssuingAgency.md new file mode 100644 index 000000000..092eaf3ff --- /dev/null +++ b/docs/standards/CX-0011-IssuingAgency/CX-0011-IssuingAgency.md @@ -0,0 +1,211 @@ + +# CX-0011 Issuing Agency v1.0.1 + +## ABSTRACT + +The issuing agency is a technical mechanism that centrally creates and +assigns business partner numbers (BPNs) for a data set of a business +partner. The issuing agency is specified in the prefix of the BPN +according to [ISO/IEC 15459](https://www.iso.org/standard/54779.html). +It ensures that a data set maps to a unique identifier and contributes +to the sharing process of business partner data. + +## 1. Introduction + +### 1.1 Audience & Scope + +> *This section is non-normative* + +This standard is relevant for: + +- Core Service Provider + +This document is focusing on the issuing agency component that is part +of the business partner data management (BPDM) use case described on +the [BPDM Catena-X Website](https://catena-x.net/en/angebote/bpdm). It +is relevant when the creation of business partner numbers for the data +sharing process and golden record process to ensure the highest data +quality is needed. It is also relevant to get an understanding on how +the mechanism works to build and maintain the issuing agency as a core +service component. + +Not in scope is the logic of the business partner number itself. There +is a separate standard for this: [Business Partner Number +Standard](https://catena-x.net/de/standard-library). + +This is not relevant for consuming data sets or BPNS for another service +or application in the Catena-X network. + +This is not relevant for sharing data or sharing member to hand over +data into the golden record process to improve the data quality of +business partner data. + +### 1.2 Context + +> *This section is non-normative* + +In general, the issuing agency is important for business partner data +management in Catena-X because it is responsible for creating the unique +identifier that identifies a legal entity in the network. By having a +centralized and responsible agency in charge of business partner data +management, Catena-X and its network participants can improve the +quality and reliability of its data and support its goals of operational +efficiency and higher data quality. + +The issuing agency is part of the whole sharing / golden record process +and will not work outstanding on its own. It is one component that is +mandatory to make the use case work. + +### 1.3 Architecture Overview + +> *This section is non-normative* + +This runtime view illustrates on a high level how the data sharing +mechanism between a sharing member, a SaaS component, including the BPN +issuing by the BPN Generator works. + +An actor can be any sharing member (company) that shares data with +Catena-X. The new business partner data object is transferred from the +enterprise layer of the sharing member to the Catena-X gate, this gate +interacts with the API of the SaaS component. The SaaS component fetches +information about their synchronization process and receives the new +data objects in response. The issuing agency that is in focus of this +standard creates a BPN and the data objects are changed accordingly. The +SaaS adapter polls the changed data and mirrors it back to the sharing +member via the SaaS component. + +With the initial process of sharing data, the sharing member receives an +optimized business partner data object with a business partner number. +After the first sharing of the data the data gets updated automatically +with the same BPN. + +![ProcessDataSharing_1.jpg](./assets/CX-0011-process-data-sharing-1.jpg) + +***Figure 1: Process data sharing*** + +### 1.4 Conformance + +As well as sections marked as non-normative, all authoring guidelines, +diagrams, examples, and notes in this specification are non-normative. +Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, +SHOULD and SHOULD NOT in this document are to be interpreted as +described in [BCP +14](https://datatracker.ietf.org/doc/html/bcp14) \[[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)\] +\[[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)\] when, and +only when, they appear in all capitals, as shown here. + +### 1.5 Proof of conformity + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they are +conform with the Catena-X standards. To validate that the standards are +applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To proof conformity of the issuing agency usage for the business partner +data management usage an operations concept must be available. The +issuing agency must be aligned with the relevant components to create a +unique identifier called BPN. In addition to that, created numbers must +follow the [business partner number +standard](https://catena-x.net/de/standard-library). + +Another valid point to proof the conformity is to show a license that +was handed out by the [Catena-X e.V.](https://catena-x.net/) + +### 1.6 Examples + +Company A transfers a new business partner data object of a legal entity +from their internal master data management system into the sharing +process to improve the data quality of this data object (e.g. get the +address of this business partner) and to get the BPNL for this data +object back into their internal system for the usage of other use cases +where they need the BPN (e.g. demand and capacity management to identify +supplier of parts in the network). + +### 1.7 Terminology + +> *This section is non-normative* + +**BPDM:** Business Partner Data Management is the domain and use case +inside Catena-X. This domain is responsible for the logic of the +business partner number, the creation of the number, the sharing process +of business partner data, the technological realization and other +services that are built up on this component. + +**BPN:** Business partner number is the unique identifier for companies. + +**BPNL** Is the business partner number of a legal entity. + +**BPNS** Is the business partner number for a site of the legal entity. + +**BPNA** Is the business partner number for the address of a site or a +legal entity. + +**Sharing Member:** Sharing members is every company that shares their +existing data objects of their business partners into the sharing +process. + +**Sharing Process:** Sharing process is the process that enables the +sharing member to share their data and to proceed the data to get the +data linked, harmonized. In this process the BPN will be attached to the +data and the golden record is created. + +**Golden Record:** Is the concept of high-quality business partner data. + +**SaaS:** Means software as a service. In this context the SaaS +component is part of the sharing process to create the golden records +and takes care that duplicates are removed, the linkage and +harmonization of the data. + +**BPDM Gate** It´s an API that can be used to put data to the sharing +process and to get the relevant data back from the process. + +**BPN Generator:** This is another wording for the issuing agency. + +Additional terminology used in this standard can be looked up in the +glossary on the association homepage. + +## 2. Issuing + +In Catena-X the BPN is the unique identifier for business partners +and MUST be issued by a central component that has the license by +the [Catena-X e.V.](https://catena-x.net/) to issue business partner +numbers. + +The issuing agency MUST create BPNs for legal entities (BPNL), sites +(BPNS) and addresses (BPNA). And each BPN that will be created MUST be +unique and MUST follow the logic of the [business partner number +standard](https://catena-x.net/de/standard-library). + +A location MUST always have at least one address with a corresponding +BPN. If this is not the case, no number will be created and data set +will be rejected by the BPDM Generator. Further additional +address MAY be added. + +The prefix of the BPN MUST follow to [ISO/IEC +15459](https://www.iso.org/standard/54779.html). + +The issuing agency SHOULD be able to receive data sets and to poll them +back. + +## 3. References + +### 3.1 Normative References + +1. CX - 0010 Business Partner Number (BPN) +2. [ISO/IEC 15459](https://www.iso.org/standard/54779.html) + +### 3.2 Non-Normative References + +> *This section is non-normative* + +1. [BPDM architecture +documentation](https://github.com/eclipse-tractusx/bpdm/blob/main/docs/arc42/architecture-documentation.adoc) +2. [BPDM use case on Catena-X +Website](https://catena-x.net/en/angebote/bpdm) + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0011-IssuingAgency/assets/CX-0011-process-data-sharing-1.jpg b/docs/standards/CX-0011-IssuingAgency/assets/CX-0011-process-data-sharing-1.jpg new file mode 100644 index 000000000..6bfe04655 Binary files /dev/null and b/docs/standards/CX-0011-IssuingAgency/assets/CX-0011-process-data-sharing-1.jpg differ diff --git a/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/CX-0012-BusinessPartnerDataPoolAPI.md b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/CX-0012-BusinessPartnerDataPoolAPI.md new file mode 100644 index 000000000..8371909ad --- /dev/null +++ b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/CX-0012-BusinessPartnerDataPoolAPI.md @@ -0,0 +1,614 @@ +# CX-0012 Business Partner Data Pool API v4.0.0 + +## FOR WHOM IS THE STANDARD DESIGNED + +This document is mainly targeted to technical individuals involved in integrating and developing against this API, as well as business individuals who are involved in compliance process of this API. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +| **Version** | **Publishing Date** | **Author** | **Description of Change** | +| ----------- | ------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1.1.0 | 2022-11-30 | | Initial version by Catena-X Association | +| 1.1.1 | 2023-06-03 | | Addendum for Conformity Assessment added | +| 2.0.0 | 2023-09-26 | | Included new API and terminology chapter | +| 2.1.0 | 2024-01-10 | | Small additions to the terminology and API specification chapters: added “business partner type” in changelog entry; added “administrative area (level 1)” as sub-object; added ISO 6709 and WGS 84 for geographic coordinates; added GET/sites; linked OpenAPI document in release branch instead of main | +| 3.0.0 | 2024-03-22 | | Added additional street attributes; removed boolean attributes in favor of enum for address types, like in the Gate API; switched to the new document structure | +| 4.0.0 | 2024-06-07 | | Added footnote to indicate that the term "site main address" is subject to change; added the CX-0018 version; changed and added the detailed asset structure; added footnote to clarify role distribution; removed terms Company Data and Sharing Member, as they are not used here; removed classification sub-object, to reintroduce it in a presumably new form in one of the next non-breaking versions of this standard; added "is Catena-X Member data" attribute; removed "api/catena/" from the endpoint definitions; added data sovereignty chapters as additional requirements; fix changelog controller endpoint for business-partners to match the reference implementation. | + +## ABSTRACT + +The Business Partner Data Management (BPDM) is a distributed service-based system, composed of a set of dedicated services, that simultaneously serve multiple stakeholders. It is based on a central data pool of business partners, which is consistent with the overall design principles of Catena-X. The main target is to create business partner data records (such as customer/supplier) with a high quality and currentness, to provide other processes with these data. This results in less rework and adjustment due to better master data quality which ultimately leads to an overall cost reduction for participating companies. Additionally, Value Added Services shall be offered to enrich those business partner data sets even further and give additional information or warnings about the business partners. Getting a 360° view on your business partners also helps with reducing costs and achieving process excellence because better decisions can be made. + +The Business Partner Pool collects business partner data records which are cleansed and enriched, so-called Golden Records, and makes them available. It is a main component of the architecture framework at Catena-X, as it enables the Catena-X Members to leverage accurate, complete, and consistent business partner data for Catena-X applications and shared services. + +The Business Partner Pool can be accessed via the standardized API described in this standard. + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following audience: + +- Core Service Provider +- Onboarding Service Provider +- Business Application Provider +- Data Provider and Consumer + +This document focuses on the Business Partner Pool API (short: Pool API) that is part of the Business Partner Data Management (BPDM) described on the [BPDM Catena-X Website](https://catena-x.net/en/offers-standards/bpdm). It is relevant for Core Service Providers who want to provide services for retrieving a cleansed, high-quality business partner data record (Golden Record) for a given business partner number (BPN). It is also relevant for onboarding service providers, business application providers as well as data providers and consumers who want to use such services. + +Not in scope are the structure and logic of the business partner number itself and the mechanism on how the business partner number is issued. There is a separate standard for this: CX-0010 Business Partner Number 2.0.0. + +Not in scope is the way of how business partner data records can be shared to create a Golden Record. There is a separate standard for this: CX-0074 Business Partner Data Gate API 3.0.0. + +Not in scope are the requirements of cleansing and enriching the business partner data records with the aim to create a Golden Record. There is a separate standard for this: CX-0076 Golden Record End to End Requirement Standards 1.2.0. + +You can find the other standards in the standard library of Catena-X: https://catena-x.net/en/standard-library. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +The Pool API is a crucial core component in Catena-X and its platform capability BPDM because it contributes to the following functions: + +1. Data Consistency: The Pool API ensures that all data related to business partners is consistent and up-to-date and can be accessed by all consumers of the API. This helps to reduce the risk of errors and inconsistencies in business partner information. +2. Centralized Data Management: The Pool API provides a centralized repository for business partner data, making it easier to manage, maintain, and update information. +3. Data Governance: The Pool API is the basis for a data governance framework and helps to enforce data quality standards, such as data completeness, accuracy, and consistency. This helps to ensure that business partner data is of high quality and can be trusted for use in various business processes. +4. Interoperability: The Pool API provides an interoperable and standardized way to access business partner data, ensuring both Core Service Provider interchangeability and streamlined data accessibility for all consumers of the API. + +There is a reference implementation for the Pool API on GitHub. It is part of a Spring Boot Kotlin open-source software project under the hood of the Eclipse Foundation and follows the Apache 2.0 licenses. + +For the complete and up-to-date API setup refer to the following website: https://github.com/eclipse-tractusx/bpdm + +For an architecture overview refer to the ARC42 documentation: https://github.com/eclipse-tractusx/bpdm/tree/release/6.0.x/docs/arc42 + +To use the Pool API in the BPDM use case apart from this standard, the following other standards should be considered by all participants for which this standard is relevant: + +- CX-0018 Dataspace Connectivity 3.0.0 + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +If sections are marked as non-normative, all authoring guidelines, diagrams, examples, and notes in these sections are non-normative. Everything else in this specification is normative. + +The key words MAY, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) [[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)] [[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)] when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +When implementing the API defined in this standard, proof of conformity must be provided by the following deliverables: + +- An OpenAPI specification defining the relevant resources for this standard +- Examples of data assets + +### 1.4 EXAMPLES + +Intentionally left blank. + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +#### 1.5.1 GENERAL + +**Golden Record:** Golden Record defines a business partner data record which successfully passed a set of predefined quality rules. These rules qualified the data record into a harmonized, standardized, and semantically unified data structure which is defined by Catena-X. The Golden Record status is a prerequisite for each BP data record to receive a valid BPN. + +#### 1.5.2 DATA MODEL + +This chapter explains the data model[^1] from a conceptual / terminology point of view. It does not include technical details of the API data model, such as: + +- differences in response and request +- differences in data stages (like input or output) +- attributes for pagination +- singular query parameters, which are not already attributes of the entities + +##### 1.5.2.1 BUSINESS PARTNER + +![Business Partner](./assets/BusinessPartner.png) + +In general, a business partner is any entity (such as a customer, a supplier, an employee, or a service provider) that does business with another entity. + +In Catena-X, a business partner is an organization (such as an enterprise or company, university, association, etc., and not a natural person) or one of its substructures that acts as unique partner within the automotive supply chain - either in the role of a direct participant, or a consultant, or a non-production-material (NPM) supplier. + +BPDM distinguishes between three business partner types to represent an organization or one of its substructures relevant for the automotive supply chain (see detailed definitions): legal entity, site, and address[^2]. + +##### 1.5.2.2 LEGAL ENTITY + +![Legal Entity](./assets/LegalEntity.png) + +In general, a legal entity is a juridical person that has legal rights and duties related to contracts, agreements, and obligations. The term especially applies to any kind of organization (such as an enterprise or company, university, association, etc.) established under the law applicable to a country. + +In Catena-X, a legal entity is a type of business partner representing a legally registered organization with its official registration information, such as legal name (including legal form, if registered), legal address and tax number. + +A legal entity has exactly one legal address, but it is possible to specify additional addresses that a legal entity owns. Thus, at least one address is assigned to a legal entity. A legal entity can own sites. Thus, many or no sites are assigned to a legal entity. A legal entity is uniquely identified by the BPNL. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| BPNL | A BPNL represents and uniquely identifies a legal entity, which is defined by its legal name (including legal form, if registered), legal address and tax number. | String | +| Legal Name | The name of the legal entity according to official registers. | String | +| Short Name | The abbreviated name of the legal entity. | String | +| Legal Form | The legal form of the legal entity. | [Legal Form](#1525-legal-form) | +| States | The list of (temporary) states of the legal entity. | List of [Legal Entity State](#15222-legal-entity-state) | +| Identifiers | The list of identifiers of the legal entity. | List of [Legal Entity Identifier](#15221-legal-entity-identifier) | +| Is Catena-X Member Data | Indicates whether the legal entity is owned and thus provided by a Catena-X Member. | Boolean | +| Created At | The date and time when the legal entity data record has been created. | Date / Time | +| Updated At | The date and time when the legal entity data record has been last updated. | Date / Time | +| Legal Address | The official, legal correspondence address to be provided to government and tax authorities and used in all legal or court documents. | [Address](#1524-address) | + +###### 1.5.2.2.1 LEGAL ENTITY IDENTIFIER + +A legal entity identifier (uniquely) identifies the legal entity, such as the German Handelsregisternummer, a VAT number, etc. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Value | The value of the identifier like “DE123465789” | String | +| Type | The type of the identifier. | [Identifier Type](#15210-identifier-type) | +| Issuing Body | The name of the official register, where the identifier is registered. For example, a Handelsregisternummer in Germany is only valid with its corresponding Registergericht and Registerart. | String | + +###### 1.5.2.2.2 LEGAL ENTITY STATE + +A legal entity state indicates if the legal entity is active or inactive[^3]. This does not describe the relation between a Catena-X Member and a business partner and whether they have active business, but it describes whether the legal entity is still operating. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ------------------------------------------------ | ----------------------------------------- | +| Valid From | The date and time from which the state is valid. | Date / Time | +| Valid To | The date and time until the state is valid. | Date / Time | +| Type | One of the state types: active, inactive. | Enum | + +##### 1.5.2.3 SITE + +![Site](./assets/Site.png) + +In general, a site is a delimited geographical area in which an organization (such as an enterprise or company, university, association, etc.) conducts business. + +In Catena-X, a site is a type of business partner representing a physical location or area owned by a legal entity, where a production plant, a warehouse, or an office building is located. + +A site is owned by a legal entity. Thus, exactly one legal entity is assigned to a site. A site has exactly one main address[^7], but it is possible to specify additional addresses (such as different gates), that belong to a site. Thus, at least one address is assigned to a site. A site can only be uploaded and modified by the owner (the legal entity), because only the owner knows which addresses belong to which site. A site is uniquely identified by the BPNS. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| BPNS | A BPNS represents and uniquely identifies a site, which is where for example a production plant, a warehouse, or an office building is located. | String | +| Name | The name of the site. This is not according to official registers but according to the name the owner chooses. | String | +| States | The list of the (temporary) states of the site. | List of [Site State](#15231-site-state) | +| Legal Entity BPN | The BPNL of the legal entity owning the site. | String | +| Is Catena-X Member Data | Indicates whether the site is owned and thus provided by a Catena-X Member. | Boolean | +| Created At | The date and time when the site data record has been created. | Date / Time | +| Updated At | The date and time the site data record has been last updated. | Date / Time | +| Main Address[^7] | The address, where typically the main entrance or the reception is located, or where the mail is delivered to. | [Address](#1524-address) | + +###### 1.5.2.3.1 SITE STATE + +A site state indicates if the site is active or inactive[^4]. This does not describe the relation between a Catena-X Member and a business partner and whether they have active business, but it describes whether the site is still operating. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ----------------------------------------- | ----------------------------------------- | +| Valid From | The date from which the state is valid. | String | +| Valid To | The date until the state is valid. | String | +| Type | One of the state types: active, inactive. | Enum | + +##### 1.5.2.4 ADDRESS + +![Address](./assets/Address.png) + +In general, an address is a collection of information to describe a physical location, using a street name with a house number and/or a post office box as reference. In addition, an address consists of several postal attributes, such as country, region (state), county, township, city, district, or postal code, which help deliver mail. + +In Catena-X, an address is a type of business partner representing the legal address of a legal entity, and/or the main address[^7] of a site, or any additional address of a legal entity or site (such as different gates). + +An address is owned by a legal entity. Thus, exactly one legal entity is assigned to an address. An address can belong to a site. Thus, one or no site is assigned to an address. An address is uniquely identified by the BPNA. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| BPNA | A BPNA represents and uniquely identifies an address, which can be the legal address of a legal entity, and/or the main address[^7] of a site, or any additional address of a legal entity or site (such as different gates). It is important to note that only the BPNL must be used to uniquely identify a legal entity. Even in the case that the BPNA represents the legal address of the legal entity, it shall not be used to uniquely identify the legal entity. | String | +| Name | The name of the address. This is not according to official registers but according to the name the sharing members agree on, such as the name of a gate or any other additional names that designate the address in common parlance. | String | +| States | The list of (temporary) states of the address. | List of [Address State](#15242-address-state) | +| Identifiers | The list of identifiers of the address. | List of [Address Identifier](#15241-address-identifier) | +| Physical Postal Address | The physical postal address of the address, such as an office, warehouse, gate, etc. | [Physical Postal Address](#1526-physical-postal-address) | +| Alternative Postal Address | The alternative postal address of the address, for example if the goods are to be picked up somewhere else. | [Alternative Postal Address](#1527-alternative-postal-address) | +| Legal Entity BPN | The BPNL of the legal entity owning the address. | String | +| Type | One of the address types: Legal Address, Site Main Address[^7], Legal and Site Main Address[^7], Additional Address. | Enum | +| Site BPN | The BPNS of the site the address belongs to. | String | +| Is Catena-X Member Data | Indicates whether the address is owned and thus provided by a Catena-X Member. | Boolean | +| Created At | The date and time when the address data record has been created. | Date / Time | +| Updated At | The date and time when the address data record has been last updated. | Date / Time | + +##### 1.5.2.4.1 ADDRESS IDENTIFIER + +An address identifier (uniquely) identifies the address, such as the Global Location Number (GLN). + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ------------------------------------------------ | ----------------------------------------- | +| Value | The value of the identifier like "0847976000005" | String | +| Type | The type of the identifier. | [Identifier Type](#15210-identifier-type) | + +##### 1.5.2.4.2 ADDRESS STATE + +An address state indicates if the address is active or inactive[^5]. This does not describe the relation between a Catena-X Member and a business partner and whether they have active business, but it describes whether the business partner is still operating at that address. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ----------------------------------------- | ----------------------------------------- | +| Valid From | The date from which the state is valid. | String | +| Valid To | The date until the state is valid. | String | +| Type | One of the state types: active, inactive. | Enum | + +##### 1.5.2.5 LEGAL FORM + +A legal form is a mandatory corporate legal framework by which companies can conduct business, charitable or other permissible activities. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Technical Key | The technical identifier of the legal form according to [ISO 20275](https://en.wikipedia.org/wiki/ISO_20275). | String | +| Name | The name of legal form according to [ISO 20275](https://en.wikipedia.org/wiki/ISO_20275). | String | +| Abbreviation | The abbreviated name of the legal form according to [ISO 20275](https://en.wikipedia.org/wiki/ISO_20275), such as AG for German Aktiengesellschaft. | String | + +##### 1.5.2.6 PHYSICAL POSTAL ADDRESS + +A physical postal address describes the physical location of an office, warehouse, gate, etc. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| Geographic Coordinates | The exact location of the physical postal address in latitude, longitude, and altitude. | [Geographic Coordinates](#1529-geographic-coordinates) | +| Country | The two-letter country code of the physical postal address according to [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1). | String | +| Administrative Area Level 1 | The administrative area of the physical postal address, such as a region within a country. | [Administrative Area (Level 1)](#1528-administrative-area-level-1) | +| Administrative Area Level 2 | The name of the locally regulated secondary country subdivision of the physical postal address, such as county within a country. | String | +| Administrative Area Level 3 | The name of the locally regulated tertiary country subdivision of the physical address, such as townships within a country. | String | +| Postal Code | The alphanumeric identifier (sometimes including spaces or punctuation) of the physical [postal address](https://en.wikipedia.org/wiki/Address_(geography)) for the purpose of sorting [mail](https://en.wikipedia.org/wiki/Mail), synonyms: postcode, post code, PIN or ZIP code. | String | +| City | The name of the city of the physical postal address, synonyms: town, village, municipality. | String | +| District | The name of the district of the physical postal address which divides the city into several smaller areas. | String | +| Street | The street of the physical postal address, synonyms: road, avenue, lane, boulevard, highway | [Street](#15261-street) | +| Company Postal Code | The company postal code of the physical postal address, which is sometimes required for large companies. | String | +| Industrial Zone | The industrial zone of the physical postal address, designating an area for industrial development, synonym: industrial area. | String | +| Building | The alphanumeric identifier of the building addressed by the physical postal address. | String | +| Floor | The number of a floor in the building addressed by the physical postal address, synonym: level. | String | +| Door | The number of a door in the building on the respective floor addressed by the physical postal address, synonyms: room, suite. | String | + +###### 1.5.2.6.1 STREET + +A street is a public road in a city, town, or village, typically with houses and buildings on one or both sides, synonyms: road, avenue, lane, boulevard, highway. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Name Prefix | The street related information, which is usually printed before the official street name on an address label. | String | +| Additional Name Prefix | The additional street related information, which is usually printed before the official street name on an address label. | String | +| Name | The name of the street. | String | +| Name Suffix | The street related information, which is usually printed after the official street name on an address label. | String | +| Additional Name Suffix | The additional street related information, which is usually printed after the official street name on an address label. | String | +| House Number | The alphanumeric identifier representing the exact location of a building within the street. | String | +| House Number Supplement | The alphanumeric identifier representing the exact location of a business partner in a building. Note this information might be further detailed semantically in the building, floor, and door attributes. However, this attribute is the only relevant for addressing the business partner. | String | +| Milestone | The alphanumeric identifier representing the exact location of an addressed object within a street without house numbers, such as within long roads. | String | +| Direction | The cardinal direction describing where the exit to the location of the addressed object on large highways / motorways is located, such as Highway 101 South. | String | + +##### 1.5.2.7 ALTERNATIVE POSTAL ADDRESS + +An alternative postal address describes an alternative way of delivery for example if the goods are to be picked up somewhere else. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | +| Geographic Coordinates | The exact location of the alternative postal address in latitude, longitude, and altitude. | [Geographic Coordinates](#1529-geographic-coordinates) | +| Country | The two-letter country code of the postal address according to [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1). | String | +| Administrative Area Level 1 | The administrative area of the alternative postal address, such as a region within a country. | [Administrative Area (Level 1)](#1528-administrative-area-level-1) | +| Postal Code | The alphanumeric identifier (sometimes including spaces or punctuation) of the alternative [postal address](https://en.wikipedia.org/wiki/Address_(geography)) for the purpose of sorting [mail](https://en.wikipedia.org/wiki/Mail), synonyms: postcode, post code, PIN or ZIP code. | String | +| City | The name of the city of the alternative postal address, synonyms: town, village, municipality. | String | +| Delivery Service Type | One of the alternative postal address types: P.O. box, private bag, boite postale. | Enum | +| Delivery Service Qualifier | The qualifier uniquely identifying the delivery service endpoint of the alternative postal address in conjunction with the delivery service number. In some countries for example, entering a P.O. box number, postal code and city is not sufficient to uniquely identify a P.O. box, because the same P.O. box number is assigned multiple times in some cities. | String | +| Delivery Service Number | The number indicating the delivery service endpoint of the alternative postal address to which the delivery is to be delivered, such as a P.O. box number or a private bag number. | String | + +##### 1.5.2.8 ADMINISTRATIVE AREA (LEVEL 1) + +An administrative area (level 1) is the country subdivision according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), such as regions within a country. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Name | The name of the country subdivision according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). | String | +| Code | The six-character alphanumeric code according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), consisting of the two-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code and a three-character alphanumeric code for the subdivision in that country, separated by a hyphen. | String | + +##### 1.5.2.9 GEOGRAPHIC COORDINATES + +Geographic coordinates describe an exact location in latitude, longitude, and altitude, according to [ISO 6709](https://en.wikipedia.org/wiki/ISO_6709) with [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84) as the currently only supported coordinate reference system. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Longitude | The geographic coordinate of a place indicating the distance to the west or east of the line passing through Greenwich, in decimal degrees ([DD](https://en.wikipedia.org/wiki/Decimal_degrees)). | Float | +| Latitude | The geographic coordinate of a place indicating its distance to the north or south of the equator, in decimal degrees ([DD](https://en.wikipedia.org/wiki/Decimal_degrees)). | Float | +| Altitude | The geographic coordinate of a place indicating its height above mean sea level, in meters. | Float | + +##### 1.5.2.10 IDENTIFIER TYPE + +![Identifier Type](./assets/IdentifierType.png) + +An identifier type defines the name or category of an identifier, such as the German Handelsregisternummer, VAT number, Global Location Number (GLN), etc. The identifier type is valid for a business partner type and used in a specific country. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| --------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Technical Key | The technical identifier of the identifier type. | String | +| Name | The name of the identifier type. | String | +| Business Partner Type | One of the types of business partners for which the identifier is valid: legal entity, address | Enum | + +##### 1.5.2.11 CHANGELOG ENTRY + +![Changelog Entry](./assets/ChangelogEntry.png) + +An entry of the changelog, which is created each time a business partner is modified and contains data about the change. The actual new state of the business partner is not included. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| --------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| BPN | The business partner number for which the changelog entry was created. Can be either a BPNL, BPNS or BPNA. | String | +| Business Partner Type | One of the types of business partners for which the changelog entry was created: legal entity, site, address. | Enum | +| Changelog Type | One of the actions for which the changelog entry was created: create, update. | Enum | +| Timestamp | The date and time when the changelog entry was created. | Date / Time | + +##### 1.5.2.12 IDENTIFIER MAPPING ENTRY + +![Identifier Mapping Entry](./assets/IdentifierMappingEntry.png) + +An identifier mapping entry of a specific identifier (of a specific identifier type) to a BPNL, BPNS or BPNA. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ---------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Identifier Value | The value of a specific identifier type for which the mapping was returned. | String | +| BPN | The business partner number for which the mapping was returned. Can be either a BPNL, BPNS or BPNA. | String | + +## 2 BUSINESS PARTNER POOL API \[NORMATIVE\] + +The Business Partner Pool API enables the access to Golden Record business partner data and provides it to other Catena-X services and consumers. The Pool API **MUST** be implemented based on the [OpenAPI 3.0.1 specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md). + +### 2.1 PRECONDITIONS AND DEPENDENCIES + +To run the API the following **SHOULD** be set up: https://github.com/eclipse-tractusx/bpdm/blob/release/6.0.x/README.md + +### 2.2 API SPECIFICATION + +#### 2.2.1 API ENDPOINTS & RESOURCES + +The Pool API **MUST** be implemented as defined in the following OpenAPI document: https://raw.githubusercontent.com/eclipse-tractusx/bpdm/release/6.0.x/docs/api/pool.json + +The resources **MUST** use the well-known HTTP request methods for CRU(D) operations: + +- POST method **MUST** be used for create requests +- PUT[^6] method **MUST** be used for update requests +- GET method **MUST** be used for read requests + +The POST method MAY also be used for read requests, if input is not given by parameters but rather by an HTTP body to bypass maximum URL length. The PUT method MAY also be used for upsert requests (create or update) if this is required. A state (active / inactive) at each entity **MUST** be used for a soft delete, so that the DELETE method SHALL NOT be used. Other HTTP request methods SHALL NOT be used, including PATCH. + +To facilitate the compliance assessment, this chapter additionally lists and describes the API resources of the Gate API per API controller. + +The following API controllers of the OpenAPI document **MUST** be implemented: + +- Legal entity controller +- Site controller +- Address controller +- Metadata controller (code lists) +- Changelog controller +- BPN controller (identifier mappings) + +Note that all resources of the OpenAPI document described in the following are **REQUIRED**. Conversely, all resources not described in the following are **OPTIONAL**. + +##### 2.2.1.1 LEGAL ENTITY CONTROLLER + +The legal entity controller **MUST** allow to create, update, or read business partners of type legal entity (having a BPNL). It also **MUST** allow to read sites and addresses of a legal entity. It **MUST** have the following resources: + +| **Legal Entity Controller Resources** | **Description** | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| POST/legal-entities | Creates a new legal entity. | +| PUT/legal-entities | Updates an existing legal entity. | +| GET/legal-entities | Returns legal entities by different search parameters. | +| GET/legal-entities/\{idValue\} | Returns a legal entity by an identifier, like BPNL, DUNS or EU VAT ID, specified by the identifier type. | +| POST/legal-entities/search | Returns legal entities by an array of BPNL. | +| POST/members/legal-entities/search | Returns only legal entities by an array of BPNL, which are owned by Catena-X Members. | +| GET/legal-entities/\{bpnl\}/sites | Returns all sites of a legal entity with a specific BPNL. | +| GET/legal-entities/\{bpnl\}/addresses | Returns all addresses of a legal entity with a specific BPNL. | + +##### 2.2.1.2 SITE CONTROLLER + +The site controller **MUST** allow to create, update, or read business partners of type site (having a BPNS). It also **MUST** allow to read addresses of a site. It **MUST** have the following resources: + +| **Site Controller Resources** | **Description** | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| POST/sites | Creates a new site. | +| PUT/sites | Updates an existing site. | +| GET/sites | Returns sites by different search parameters. | +| GET/sites/\{bpns\} | Returns a site by its BPNS. | +| POST/sites/search | Returns sites by an array of BPNS and/or an array of corresponding BPNL. | +| POST/members/sites/search | Returns only sites by an array of BPNS and/or an array of corresponding BPNL, which are owned by Catena-X Members. | + +##### 2.2.1.3 ADDRESS CONTROLLER + +The address controller **MUST** allow to create, update, or read business partners of type address (having a BPNA). It **MUST** have the following resources: + +| **Address Controller Resources** | **Description** | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| POST/addresses | Creates a new address. | +| PUT/addresses | Updates an existing address. | +| GET/addresses | Returns addresses by different search parameters. | +| GET/addresses/\{bpna\} | Returns an address by its BPNA. | +| POST/addresses/search | Returns addresses by an array of BPNA and/or an array of corresponding BPNS and/or an array of corresponding BPNL. | +| POST/members/addresses/search | Returns only addresses by an array of BPNA and/or an array of corresponding BPNS and/or an array of corresponding BPNL, which are owned by Catena-X Members. | + +##### 2.2.1.4 METADATA CONTROLLER (CODE LISTS) + +The metadata controller **MUST** allow to create or read legal forms, identifier types, and administrative areas on level 1. It **MUST** have the following resources: + +| **Metadata Controller Resources** | **Description** | +| --------------------------------- | --------------------------------------------------------------------------- | +| POST/legal-forms | Creates a new legal form. | +| POST/identifier-types | Creates a new identifier type. | +| POST/administrative-areas-level1 | Creates a new administrative area on level 1. | +| GET/legal-forms | Returns all legal forms. | +| GET/identifier-types | Returns all identifier types filtered by business partner type and country. | +| GET/administrative-areas-level1 | Returns all administrative areas on level 1. | + +##### 2.2.1.5 BPN CONTROLLER (IDENTIFIER MAPPINGS) + +The BPN controller **MUST** allow to read identifier mappings between identifiers (such as DUNS, EU VAT ID, CX Member Identifier, etc.) on one side and BPNL, BPNS, BPNA on the other side. It **MUST** have the following resources: + +| **BPN Controller Resources** | **Description** | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| POST/bpn/search | Returns a list of identifier mappings of an identifier to a BPNL, BPNA or BPNS, specified by a business partner type, identifier type and identifier values. | + +##### 2.2.1.6 CHANGELOG CONTROLLER + +The changelog controller **MUST** allow to read change log entries of legal entities, sites and addresses. It **MUST** have the following resources: + +| **Changelog Controller Resources** | **Description** | +| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| POST/business-partners/changelog/search | Returns changelog entries of legal entities, sites and addresses as of a specified timestamp, optionally filtered by a list of BPNL, BPNS and BPNA, or business partner types. | +| POST/members/changelog/search | Returns only changelog entries of legal entities, sites and addresses, which are owned by Catena-X Members, as of a specified timestamp, optionally filtered by a list of BPNL, BPNS and BPNA, or business partner types. | + +#### 2.2.2 AVAILABLE DATA TYPES + +The API **MUST** use JSON as the payload format transported via HTTP. Other formats MAY be added. These are then, however, **OPTIONAL**. + +#### 2.2.3 DATA ASSET STRUCTURE + +The following data assets **MUST** be registered at the Core Service Provider so that the Catena-X Member can negotiate an API usage contract with the Core Service Provider and access the BPDM Pool (hosted by the Core Service Provider) through these assets [^8]: + +| **Type** | **Subject** | **Version** | **Description** | +| -------- | ------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| BPDMPool | ReadAccessPoolForCatenaXMember | 6.0 | Grants the Catena-X Member read access to the Pool API. This can be used to read legal entity, site, address, legal form, identifier type and administrative area level 1 data. To that end, it also grants read access to the respective changelog and identifier mappings, as well as relational data. | + +Read access for legal entities, sites and address **MUST** be restricted to Catena-X Member data (see the corresponding attribute for legal entity, site and address), because the Pool may also contain legal entities, sites and address, which are not owned by Catena-X Members. + +Write resources (create and update) of the Pool API **MUST NOT** be called from outside of the Catena-X operating environment. Consequently, data assets for them are **NOT REQUIRED**. + +Example data asset ([*dct:type*](https://purl.org/dc/terms/type) for asset type, [*dct:subject*](https://purl.org/dc/terms/subject) for asset subject, [*dct:description*](https://purl.org/dc/terms/description) for asset description and *cx-common:version* for asset version from the table above): + +```json +{ + "@context": { + "dct": "https://purl.org/dc/terms/", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "cx-common": "https://w3id.org/catenax/ontology/common#", + }, + "@type": "Asset", + "@id": "e94272b1-9831-458f-8986-c63c4973ea60", + "properties": { + "dct:type": { + "@id": "cx-taxo:BPDMPool" + }, + "dct:subject": { + "@id": "cx-taxo:ReadAccessPoolForCatenaXMember" + }, + "dct:description": "Grants the Catena-X Member read access to the Pool API. This can be used to read legal entity, site, address, legal form, identifier type and administrative area level 1 data. To that end, it also grants read access to the respective changelog entries and identifier mappings, as well as relational data.", + "cx-common:version": "6.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "https:///pool/api/v6/members", + "oauth2:tokenUrl": "https:///auth/realms//protocol/openid-connect/token", + "oauth2:clientId": "", + "oauth2:clientSecretKey": "", + "proxyMethod": true, + "proxyPath": true, + "proxyQueryParams": true, + "proxyBody": true + } +} +``` + +The OAuth2 client permissions **MUST** be configured to solely allow access to the API resources defined in the corresponding asset, checking HTTP method, path, query parameters and body of the HTTP request sent to the data plane public API which acts as a proxy for the BPDM Pool API[^9]. + +#### 2.2.4 ERROR HANDLING + +The following http response codes **MUST** be defined for all resources: + +- 200 - OK +- 400 - Bad Request +- 401 - Unauthorized +- 403 - Forbidden +- 404 - Not Found +- 500 - Internal Server Error + +HTTP Status Code Registry **MUST** be adhered to in the implementation for the decision on when to use which error code: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml + +#### 2.2.5 ADDITIONAL REQUIREMENTS + +##### 2.2.5.1 CONVENTIONS FOR USE CASE POLICY IN CONTEXT OF DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +##### 2.2.5.2 ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number. + +- Membership +- BPNL + +##### 2.2.5.3 ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +- [Pool API specification 6.0.x](https://raw.githubusercontent.com/eclipse-tractusx/bpdm/release/6.0.x/docs/api/pool.json) +- [ISO 20275](https://en.wikipedia.org/wiki/ISO_20275) +- [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) + - [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) + - [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) + +- [ISO 6709](https://en.wikipedia.org/wiki/ISO_6709) +- [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84) + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- [BPDM Catena-X Website](https://catena-x.net/en/offers-standards/bpdm) + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +- [Business Partner Pool API 6.0.x](https://github.com/eclipse-tractusx/bpdm/tree/release/6.0.x/bpdm-pool-api/src/main/kotlin/org/eclipse/tractusx/bpdm/pool/api) + +## ANNEXES + +## FIGURES + +> *This section is non-normative* + +Intentionally left blank. + +## TABLES + +> *This section is non-normative* + +Intentionally left blank. + +[^1]: Note that PlantUml is used for the conceptual UML diagrams in this document (A = abstract class; green E = entity; C = class; red E = enumeration). An abstract class has no actual representation in the OpenAPI implementation. An entity is usually implemented by an own OpenAPI controller with resources and usually is the root in a payload, while a class is a sub node in the payload. An enumeration is a set of predefined values. + +[^2]: These types always imply a business partner which means that legal entity, site, and address are types of business partners. + +[^3]: Note that this a currently a soft-delete approach and not a business state. However, this can be adapted in the next version of this standard. + +[^4]: Note that this a currently a soft-delete approach and not a business state. However, this can be adapted in the next version of this standard. + +[^5]: Note that this a currently a soft-delete approach and not a business state. However, this can be adapted in the next version of this standard. + +[^6]: Note that in case of a PUT the corresponding resources expect to receive the full updated record, including values that did not change. + +[^7]: Note that there is currently a debate as to whether a site is only a consolidation of addresses (BPNA), with all addresses being equally ranked, since a "main" address can't always be defined at this point in time. This may lead to changes in the next update of this standard. + +[^8]: Note that further assets will most probably be introduced in one of the next versions of this standard. + +[^9]: Note that the definition of the data assets depends on the current implementation state of the reference implementation (Tractus-X Eclipse Dataspace Connector). Therefore the data assets represent permissions on APIs, whereas they should actually only represent APIs. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/Address.png b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/Address.png new file mode 100644 index 000000000..1cf904e2a Binary files /dev/null and b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/Address.png differ diff --git a/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/BusinessPartner.png b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/BusinessPartner.png new file mode 100644 index 000000000..f72b671e3 Binary files /dev/null and b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/BusinessPartner.png differ diff --git a/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/ChangelogEntry.png b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/ChangelogEntry.png new file mode 100644 index 000000000..228a5444c Binary files /dev/null and b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/ChangelogEntry.png differ diff --git a/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/IdentifierMappingEntry.png b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/IdentifierMappingEntry.png new file mode 100644 index 000000000..39843027e Binary files /dev/null and b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/IdentifierMappingEntry.png differ diff --git a/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/IdentifierType.png b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/IdentifierType.png new file mode 100644 index 000000000..1cb10cace Binary files /dev/null and b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/IdentifierType.png differ diff --git a/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/LegalEntity.png b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/LegalEntity.png new file mode 100644 index 000000000..bd0e4a3cd Binary files /dev/null and b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/LegalEntity.png differ diff --git a/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/Site.png b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/Site.png new file mode 100644 index 000000000..cff110457 Binary files /dev/null and b/docs/standards/CX-0012-BusinessPartnerDataPoolAPI/assets/Site.png differ diff --git a/docs/standards/CX-0013-IdentityOfMemberCompanies/CX-0013-IdentityofMemberCompanies.md b/docs/standards/CX-0013-IdentityOfMemberCompanies/CX-0013-IdentityofMemberCompanies.md new file mode 100644 index 000000000..256377b33 --- /dev/null +++ b/docs/standards/CX-0013-IdentityOfMemberCompanies/CX-0013-IdentityofMemberCompanies.md @@ -0,0 +1,166 @@ +# CX-0013 Identity of Member Company v2.0.0 + +## ABSTRACT + +Identity and Access management (IAM) enables any non-anonymous interactions, meaning independent identification and description of the actors in a verifiable and reliable way. The identification of assets +or digital twins is not in the scope of IAM. +A company in the context of IAM is a digital identity matched to a respective participant of Catena-X. +The digital identities of employees and technical users are always tied to the company for which he or she +acts. +This standard documentation defines the technical foundation and the structure used for the identity of the company participating in Catena-X. + +## 1. INTRODUCTION + +Identity and Access Management (IAM) is a mandatory basic infrastructure for every IT-System. The identity of any entity and actor (company, user, or technical client/connector) is the summary of the describing attributes (e.g., Company Name, Address, Tax Number, etc.). Catena-X is intended to be a network-of-networks which consequently means that there cannot be a single Identity Provider (IdP) for the company identities nested in one network. The company must be identifiable in an independent way and interoperable in all networks. The identity of users (employees of a company) and technical users (e.g., the Connector) in Catena-X, must be bound to the company they are acting on behalf of. + +### 1.1 AUDIENCE & SCOPE + +#### AUDIENCE + +The purpose of this standardization request is to unify the Digital Company Identity. +This document is relevant for the following roles, as the must be certified against it: + +- Core Service Providers as they offer the registration to the Catena-X network +- Enablement Service Providers which offer Wallet Services to the Core Service Providers + +#### SCOPE + +> *This section is non-normative.* + +This document covers the requirements for the participant's identity and the according technical solution to that, in this case the identity Wallet. It describes the following: + +- The basic definition of the usage of Decentralized Identifiers +- The fundamentals of a Wallet service + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative.* + +The purpose of this standardization request is to unify the Digital Company Identity in a self-sovereign manner. The digital identity of a participant is the basis of any interaction with other partners. To ensure independence and data sovereignty from one identity provider this identity - as the summary of the describing attributes - must be under the sovereignty of the respective partner company. + +Self-Sovereign identity (SSI) is a concept that gives individuals and organizations control over their own digital identity and the information required for identity verification, through principles such as user control, transparency, access to data, and transportability. SSI is implemented using open standards like Decentralized Identifiers (DIDs), Decentralized Public Key Infrastructure (DPKI), and Verifiable Credentials. + +This approach serves and ensure interoperability as well as data sovereignty. + +### 1.3 ARCHITECTURE OVERVIEW + +> *This section is non-normative.* + +Not applicable. + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is non-normative.* + +`Core Service Provider` + +All Core Service Providers **MUST** ensure, that the created DID document for the participant follow the `did:web` standard described here https://w3c-ccg.github.io/did-method-web/. + +To validate these criteria of conformance to the Use Case Framework Agreements please collect the following documents: + +- Arch42 Documentation explaining the architecture, process flows and data structures of the implementation. + +Hand this documentation to the conformity assessment body + +`Enablement Service Provider` + +All Core Service Providers **MUST** ensure, that the Wallet service they offer create DID documents for the participants following the `did:web` standard described here https://w3c-ccg.github.io/did-method-web/. + +To validate these criteria of conformance to the Use Case Framework Agreements please collect the following documents: + +- Arch42 Documentation explaining the architecture, process flows and data structures of the implementation. + +Hand this documentation to the conformity assessment body + +### 1.6 EXAMPLES + +Not applicable. + +### 1.7 TERMINOLOGY + +> *This section is non-normative.* + +Not applicable. + +## 2. DECENTRALIZED IDENTIFIER + +> *This section is normative.* + +Decentralized Identifier as a technological approach to form a Self-Sovereign Identity is based on cryptographic technologies which provide the ability to exchange identity information in a secure way. +Based on open standards of the W3C https://www.w3.org/TR/did-core/ a DID also ensures interoperability while also ensuring data sovereignty according to the identity data of the participant. + +To manage a DID a Wallet is used. + +### 2.2 WALLET SERVICE + +> *This section is normative* + +SSI will be an integral part of Catena-X. This requires a wallet for each participant to store his private keys to issue verifiable credentials and to receive Verifiable Credentials issued for him. Therefore, in the course of registration, each participant must be equipped with an instance of the Wallet to store credentials. + +To ensure the processes needed for data exchange the Wallet service provides the following core functionalities described in `CX-0149 VERIFIED COMPANY IDENTITY v1.1.0`. + +### 2.3 DID METHOD + +The DID method describes the implementation of a DID network, which includes the type of the anchoring of the DIDs and the Verifiable Data Registry. +It is used for resolution of the DID with the goal to receive the DID Document, described in `CX-0049` v2.0.0, done with a resolver. A reference implementation of a DID resolver being able to resolve multiple DID methods is the "universal resolver" which can be found here +https://github.com/decentralized-identity/universal-resolver + +The DIDs for the participants, created by the Core Service Provider at the moment of registration and managed by the Wallet service, are based in the DID method `did:web`, specified here: +https://w3c-ccg.github.io/did-method-web/ + +### 2.3 REGISTRATION PROCESS + +To ensure that every participant of Catena-X has a valid DID, a new participating company will be provided a tenant in the Wallet service at the moment of registration to become an official Catena-X partner. + +The required company information for the registration process needs to be provided by the participant and validated by the Core Service Provider. +After successful registration, the Catena-X specific Business Partner Number (BPN) VC and Catena-X specific Membership VC will be issued to the Wallet tenant of the participant. + +```text +The registration process is described in detail in CX-0149:1.0 DATA SPACE IDENTITY AND IDENTIFICATION following the definition of the Identity and Trust Protocol (IATP) . +``` + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +> *This section is normative.* + +- CX-0049:2.0 DID Document Schema +- CX-0149:1.0 Verfified Company Identity + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative.* + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative.* + +Not applicable. + +## ANNEXES + +### FIGURES + +> *This section is non-normative.* + +Not applicable. + +### TABLES + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0014-EmployeesAndTechnicalUsers/CX-0014-EmployeesAndTechnicalUsers.md b/docs/standards/CX-0014-EmployeesAndTechnicalUsers/CX-0014-EmployeesAndTechnicalUsers.md new file mode 100644 index 000000000..caa4b6f2f --- /dev/null +++ b/docs/standards/CX-0014-EmployeesAndTechnicalUsers/CX-0014-EmployeesAndTechnicalUsers.md @@ -0,0 +1,124 @@ +# CX-0014 Employees and Technical Users v1.0.1 + +## ABSTRACT + +Identity and Access Management (IAM) is a mandatory basic infrastructure +for every IT-System. The identity of any entity and actor (company, +user, or technical client/connector) is the summary of the describing +attributes (e.g., Company Name, Address, Tax Number, etc.). Catena-X is +intended to be a network-of-networks which consequently means that there +cannot be a single Identity Provider (IdP) for the company identities +nested in one network. The company must be identifiable in an +independent way and interoperable in all networks. The identity of users +(employees of a company) and technical users (e.g., EDC) in Catena-X, +must be bound to the company they are acting on behalf of. + +## 1. Introduction + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +List for which roles the standard is relevant: + +- Core Service Provider +- Data Provider / Consumer +- Business Application Provider +- Enablement Service Provider +- Onboarding Service Provider +- Consulting Services Provider + +This Standard applies to all participants and their representative that interact with each other. The representatives can either be the employees --or users of a participant- or the technical users --in case of Catena-X the EDCs- of a participant. + +### 1.2 Context + +> *This section is non-normative* + +Standardization of the digital identity of technical users and employees +who are bound to the company they operate for. The goal is to protect +data. It ensures that permissions and users can be managed in all +systems and applications. + +### 1.3 Conformance + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, +diagrams, examples, and notes in this specification are non-normative. +Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, +SHOULD and SHOULD NOT in this document are to be interpreted as +described in [BCP +14](https://datatracker.ietf.org/doc/html/bcp14) \[[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)\] +\[[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)\] when, and +only when, they appear in all capitals, as shown here. + +### 1.4 Proof of Conformity + +> *This section is non-normative* + +All participants and their solutions will need to prove they conform +with the Catena-X standards. To validate that the standards are applied +correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +A test bed must be set up, to prove the correctness of the data +provisioning. A generic test set of data must get processed, to prove +the expected results. + +### 1.5 Terminology + +> *This section is non-normative* + +Additional terminology used in this standard can be looked up in the +glossary on the association homepage. + +## 2. Main Content + +**This standard is not certifiable yet (only release 3.1 onwards)** + +Core Service provider MUST proof that they apply to the OIDC standard +found on the spec [Specifications \| +OpenID](https://openid.net/developers/specs/) to manage the identities +and access policies described in **CX - 0015 IAM & ACCESS CONTROL +PARADIGM FOR USERS AND CLIENTS** which + +- must be reachable by other partners +- ownership must be verifiable + +Core Service provider MUST prove that they provide a managed identity +solution based on OIDC. Core Service provider MUST prove that they make +the use for a self-hosted IdP based on OIDC possible for any +participant.  If a core service provider provides an OIDC service he +MUST prove that every customer has its own delimited area for his users +and that no users of any customer has access to any data of another +customer. The users of a specific customer must be assignable to only +the customer they belong to. + +To validate these criteria for the OIDC service please collect the +following documents: + +- Arch42 Documentation explaining the architecture, access management and process flows of the implementation +- The URI / URL of the OIDC instance + +Hand this documentation to the conformity assessment body + +An operating environment which provides an OIDC service SHOULD operate an OIDC instance that supports Attribute Based Access Control described in the following standard *\[*[Guide to Attribute Based Access Control (ABAC) Definition and Considerations (nist.gov)](https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-162.pdf)*\]* + +A technical user (e.g. EDC) MUST provide at least the BPN of the Data Consumer/ Producer as an attribute inside the OIDC token at any interaction. + +To validate these criteria for the OIDC service please collect the following documents: + +- Arch42 Documentation explaining the architecture, access management and process flows of the implementation + +Hand this documentation to the conformity assessment body + +## 3. References + +### 3.1 Normative References + +- CX-0015 IAM & ACCESS CONTROL PARADIGM + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0018-DataspaceConnectivity/CX-0018-DataspaceConnectivity.md b/docs/standards/CX-0018-DataspaceConnectivity/CX-0018-DataspaceConnectivity.md new file mode 100644 index 000000000..6675cf9a3 --- /dev/null +++ b/docs/standards/CX-0018-DataspaceConnectivity/CX-0018-DataspaceConnectivity.md @@ -0,0 +1,251 @@ +# CX-0018 Dataspace Connectivity v3.0.0 + +## ABSTRACT + +This document specifies the communication requirements for data exchange between participants in the Catena-X data +ecosystem. The aim is to ensure interoperability and data sovereignty at the same time. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +- In order to avoid lock-in effects, this standard intentionally does **not** describe a specific component (like the + Eclipse Dataspace Connector in the last version), but how such a communication component must behave in order to be + certified for the Catena-X data space. +- Adopt pinned versions of IATP, DSP, policy definitions +- Specify HTTPS and AmazonS3 transfer processes + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +#### AUDIENCE + +The role definition is based on the definition of +the [CX Operating Model v2.1](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf). + +The standard is relevant for the following roles, as they must be certified against it: + +- Core Service Provider (A/B) +- Enablement Service Provider +- Business Application Provider +- Data Provider/Consumer + +> Note: The normative section of this standard uses the DSP-definitions of "Consumer" and "Provider". Any of the +> aforementioned Catena-X-roles can assume either DSP-role. + +The standard is relevant for the following role, as they must certify against this standard: + +- Conformity Assessment Body + +The standard is relevant for the following role, as they carry out their advisory on the basis of this standard. + +- Advisory Provider + +#### SCOPE + +This document covers the requirements for dataspace connectivity. It describes + +- how communication between dataspace participants must take place, +- which transfer type profiles must be used, +- how communication with credential services must take place, +- which conventions apply with regard to policy constraints +- and which conventions apply to datasets. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +The connector is the main technical component that implements dataspace connectivity including data sovereignty and +interorganizational interoperability. It is part of the enablement services, which are intended to enable participation +in the Catena-X ecosystem. More information about the Enablement Services can be found under +the [Whitepaper Enablement Services](https://catena-x.net/fileadmin/_online_media_/231006_Whitepaper_EnablementServices.pdf). + +The following figure shows how the connector fits into the overall framework of Catena-X to exchange data. + +![Framework of data exchange](./assets/Framework_of_data_exchange.png) + +*Figure 1: Framework of data exchange* + +> Note: At time of the release, the Identity Wallet solution is not decentralized yet. However, this standard already +> provides most of the infrastructure to operate Wallets (IATP-Credential-Services) in a distributed manner. +> More information about the SSI-infrastructure can be found in the relevant standards. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this +specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT +** +in this document are to be interpreted as described in BCP 14 RFC2119, RFC8174 when, and only when, they +appear in all capitals, as shown here. + +### 1.4 TERMINOLOGY + +| Term | Description | Reference | +|----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| +| International Data Spaces Association (IDSA) | Organisation that provides standards and architecture solutions for secure, sovereign data sharing within so-called dataspaces | https://internationaldataspaces.org | +| Dataspace Protocol (DSP) | Set of specifications designed to facilitate interoperable data sharing within a dataspace, currently governed by the IDSA | https://github.com/International-Data-Spaces-Association/ids-specification | +| Connector | (Catena-X) Technical component that allows business applications to interact with each other within a dataspace | https://github.com/eclipse-tractusx/tractusx-edc | +| (Catena-X) Business Applications | (Catena-X) Applications that enable functionality of different use cases, hosted by a data provider or consumer itself or by a business application provider | https://eclipse-tractusx.github.io/developer | +| Catena-X Marketplace | The Marketplace inside a portal, allowing participants of the Catena-X network to search and select Catena-X Business Applicactions | https://catena-x.net/en/offers/portal-marketplace | +| Business Partner Number (BPN) | Every participant in the Catena-X network has a unique, unchangeable identifier, called business partner number (BPN). The legal entity of an organization is represented by the Business Partner Number Legal Entity (BPNL) | [CX - 0010 Business Partner Number](https://catena-x.net/de/standard-library) | +| Data Catalog Vocabulary (DCAT) | RDF vocabulary designed to facilitate interoperability between data catalogs published on the Web | https://www.w3.org/TR/vocab-dcat-3 | +| Open Data Rights Language (ODRL) | Policy expression language that provides a flexible and interoperable information model, vocabulary, and encoding mechanisms for representing statements about the usage of content and services | https://www.w3.org/TR/odrl-model, https://www.w3.org/TR/odrl-vocab, https://w3c.github.io/odrl/bp | + +- The terms *Connector, Provider, Participant Agent* are adopted from the DSP. +- The term *Credential Service* is adopted from the IATP. +- The terms *Core Service Provider A/B (CSP A/B)*, *Onboarding Service Provider (OSP)*, *Enablement Service Provider ( + ESP)*, *Business Application Provider (BAP)*, *Advisory Provider (AP)* and *Conformity Assessment Body (CAB)* are + adopted from the [CX Operating Model v2.1](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf) + +## 2 MAIN CONTENT + +> *This section is normative* + +This section uses the following prefixes as abbreviations for namespaces + +- `"dct": "http://purl.org/dc/terms/"` +- `"dspace": "https://w3id.org/dspace/2024/1/"` +- `"odrl": "https://www.w3.org/ns/odrl/2/"` +- `"dcat": "http://www.w3.org/ns/dcat#"` + +### 2.1 Communication between Dataspace Participants + +Dataspace *Participants* exchange data via their *Participant Agents*. They are a logical component that communicates +via a set of well-defined messages. + +Participant Agents MUST facilitate data exchange according to the HTTPS binding defined in the [Dataspace Protocol +2024-01](#31-normative-references). + +Providers and Consumer MUST expose the specified endpoints for the + +- Catalog Protocol +- Contract Negotiation Protocol +- Transfer Process Protocol +- Version Metadata + +as specified in the HTTPS binding of the Dataspace Protocol 2024-01. + +### 2.2 Transfer Type Profiles + +In their `dcat:Catalog` response to a `dspace:CatalogRequestMessage`, for each Dataset, a Provider MUST return a +`dcat:Distribution` signifying what Transfer Profile a Consumer can use to obtain data. + +Providers MUST be able to serve data according to that signal when data transfer is requested by a consumer +via a `dspace:TransferRequestMessage`. + +> Despite the IRIs `dspace:HttpData-PULL` and `dspace:AmazonS3-PUSH` are not yet included in the DSP-context, they will +> be used as preliminary identifiers. + +Providers MAY offer any of the following Transfer Type Profiles: + +#### 2.2.1 HttpData-PULL + +A Consumer MUST send a `dspace:TransferRequestMessage` with `dct:format`:`dspace:HttpData-PULL` and an +empty `dspace:dataAddress` property. + +A Provider MUST send a `dspace:TransferStartMessage` with sufficient information in the `dspace:dataAddress` property so +that a request to the `dspace:endpoint` may succeed when decorated with HTTP-headers constructed from +the `dspace:endpointProperties`' with `dspace:name` as key and `dspace:value` as value respectively. + +A Provider Connector MUST ensure that the requested backend system has sufficient context from the negotiation +to evaluate the legitimacy of the request. + +A Consumer may then use the provided data to execute requests against the endpoint. + +> Despite the token, the endpoint still has the right to refuse serving a request. This may occur for instance when +> a consumer attempts to PUT against a resource but is only allowed to GET. + +#### 2.2.2 AmazonS3-PUSH + +A Consumer MUST send a `dspace:TransferRequestMessage` with `dct:format`:`dspace:AmazonS3-PUSH` and +a `dspace:dataAddress` property +so that triggering a transfer to the `dspace:endpoint` decorated with the data relevant `dspace:endpointProperties` may +succeed. + +A Provider MUST send a `dspace:TransferStartMessage` and an empty `dspace:dataAddress` property. He MUST execute a +transfer +as specified by the received request. + +### 2.3 Communication with a Credential Service + +This standard assumes that each Participant has been issued a set of Verifiable Credentials (VCs) according to the +relevant +Catena-X standards. These VCs are stored in a Credential Service. + +A Consumer MUST be able to retrieve an access token according to the Verifiable Presentation Protocol (VPP) that is part +of the IATP (Identity and Trust Protocol). This corresponds to Request 1 in the presentation flow where this Consumer +acts as Client. + +A Provider MUST be able to receive and securely verify an access token and derive information on a Consumer's +Credential Service in order to execute IATP VPP Request 4. This corresponds to the role of Verifier. + +### 2.4 Conventions for Policy Constraints + +`odrl:Offer` objects contained in a `dcat:Catalog` SHOULD carry `odrl:Constraint`s that are specified in the +[CX-ODRL-Profile](#31-normative-references). Subsequent standards are encouraged to specify further +restrictions of said profile, especially on the `odrl:rightOperand`s. The following list compiles a set of well-defined +policies that Participants SHOULD include in their offers and guidance on how to check them. + +| Name | leftOperand (expanded IRI) | operator
(compacted IRI) | valid rightOperands (literal) | validation mechanism | +|-----------------------------|------------------------------------------------------|--------------------------------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| MembershipConstraint | `https://w3id.org/catenax/policy/Membership` | `odrl:eq` | `active` | Membership Credential (CX - 0149) | +| UseCaseConstraints | `https://w3id.org/catenax/policy/FrameworkAgreement` | `odrl:eq` | `[usecasename]:[version]` | UseCaseFrameworkAgreementCredential (CX - 0050)
The exact mapping logic from credential and to rightOperand specified in [tractusx-profiles](https://github.com/eclipse-tractusx/tractusx-profiles/blob/64f83dde1432573db456500f091f223929d43307/cx/policy/specs/policy.mapping.md). | +| ContractReferenceConstraint | `https://w3id.org/catenax/policy/ContractReference` | `odrl:eq` | `[string]:[version]` | *unchecked* | +| UsagePurposeConstraint | `https://w3id.org/catenax/policy/UsagePurpose` | `odrl:eq` | `[string]:[version]` | *unchecked* | + +> Note: The list is available in machine-readable form with links to the respective legal documents in the +> catenax-ev/cx-odrl-profile repository. + +Providers SHOULD chain constraints (if necessary) via `odrl:and`. Examples can be found +in [catenax-ev/cx-odrl-profiles](#32-non-normative-references). + +Providers MUST perform access control checks on their data offers as a `dcat:Catalog` object may expose +information restricted by governance and regulation. + +### 2.5 Conventions for Datasets + +A Provider MUST annotate all instances `dcat:Dataset` in a `dcat:Catalog` with the following properties: + +- `dct:type` holding an object with at least a `@id` property pointing to a concept describing what type of API this + Dataset represents. Subsequent standards define the exact value this property shall hold, depending on the Business + scenario. The set of concepts is maintained in the taxonomy `https://w3id.org/catenax/taxonomy#` and MUST + extend the concept https://w3id.org/catenax/taxonomy#Asset. +- `cx-common:version` holding a SemVer-conformant string indicating the API version of the API that was typed by the + `dct:type` property. Subsequent standards define the exact value this property shall hold, depending on the Business + scenario. + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +- [IDSA Dataspace Protocol 2024-01](https://github.com/International-Data-Spaces-Association/ids-specification/releases/tag/2024-1) +- [Identity And Trust Protocol v0.8](https://github.com/eclipse-tractusx/identity-trust/blob/0.8.1/specifications/verifiable.presentation.protocol.md) +- [CX - 0050 Framework Agreement Credential v1.2.0](https://catena-x.net/de/standard-library) +- [CX - 0149 Verfied Company Identity v1.0.0](https://catena-x.net/de/standard-library) +- [Tractus-X Profiles v1.0](https://github.com/eclipse-tractusx/tractusx-profiles/releases/tag/1.0.0) + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- [Catena-X Profile of the Open Digital Rights Language (ODRL)](https://github.com/catenax-eV/cx-odrl-profile) +- [Connector Kit](https://eclipse-tractusx.github.io/docs-kits/next/category/connector-kit) + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +- [Tractus-X EDC](https://github.com/eclipse-tractusx/tractusx-edc) + +## ANNEXES + +### FIGURES + +Figure 1: Framework of data exchange + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0018-DataspaceConnectivity/assets/Framework_of_data_exchange.png b/docs/standards/CX-0018-DataspaceConnectivity/assets/Framework_of_data_exchange.png new file mode 100644 index 000000000..2f1c1531d Binary files /dev/null and b/docs/standards/CX-0018-DataspaceConnectivity/assets/Framework_of_data_exchange.png differ diff --git a/docs/standards/CX-0018-DataspaceConnectivity/assets/architecture-v2.png b/docs/standards/CX-0018-DataspaceConnectivity/assets/architecture-v2.png new file mode 100644 index 000000000..a48f542c8 Binary files /dev/null and b/docs/standards/CX-0018-DataspaceConnectivity/assets/architecture-v2.png differ diff --git a/docs/standards/CX-0027-ProductCarbonFootprintAspectModel/CX-0027-ProductCarbonFootprintAspectModel.md b/docs/standards/CX-0027-ProductCarbonFootprintAspectModel/CX-0027-ProductCarbonFootprintAspectModel.md new file mode 100644 index 000000000..c3cabc644 --- /dev/null +++ b/docs/standards/CX-0027-ProductCarbonFootprintAspectModel/CX-0027-ProductCarbonFootprintAspectModel.md @@ -0,0 +1,441 @@ + +# CX-0027 Product Carbon Footprint Aspect Model v1.0.0 + +## 1. Introduction + +PCF is the abbreviation for Product Carbon Footprint. In Catena-X, the +aim is to create transparency about the PCF in the supply chain. From a +normative perspective, each Product (Carbon) Footprint represents the +carbon footprint of a product with values in accordance with the WBCSD +(World Business Council for Sustainable Development)/ Pathfinder +framework. In contrast, from a non-normative perspective, each Product +Footprint relates to a specific product, identified by one or more +product identifiers. Moreover, the Product Footprint is modelled as a +multi-purpose container for product-specific factors. + +## 2. Purpose + +This standardization introduces the standardized aspect model for the +product carbon footprint with corresponding JSON schemas and payloads +for guidance and orientation on how to provision and exchange the +corresponding data within Catena-X. + +Note: The presented aspect model is in version 2.0.0. + +## 3. Aspect Model + +The aspect model and the corresponding JSON schema are presented below. + +### 3.1. Model + +![PCF Aspect Model](./assets/CX-0027.svg) + +Figure 1: PCF Aspect Model + +Furthermore, the corresponding JSON Schema is as follows: + +```json +{ + "$schema": "http://json-schema.org/draft-04/schema", + "type": "object", + "components": { + "schemas": { + "urn_bamm_io.catenax.pcf_2.0.0_IdTrait": { + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" + }, + "urn_bamm_io.catenax.pcf_2.0.0_SpecVersionTrait": { + "type": "string", + "pattern": "\\d+\\.\\d+\\.\\d+" + }, + "urn_bamm_io.catenax.pcf_2.0.0_ProductFootprintVersionCharacteristic": { + "type": "number", + "minimum": 1 + }, + "urn_bamm_io.openmanufacturing_characteristic_2.0.0_Timestamp": { + "type": "string", + "pattern": "-?([1-9][0-9]{3,}|0[0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T(([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]+)?|(24:00:00(\\.0+)?))(Z|(\\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))?" + }, + "urn_bamm_io.catenax.pcf_2.0.0_NonEmptyString": { + "type": "string" + }, + "urn_bamm_io.catenax.pcf_2.0.0_CompanyIdsCharacteristic": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "urn_bamm_io.openmanufacturing_characteristic_2.0.0_Text": { + "type": "string" + }, + "urn_bamm_io.catenax.pcf_2.0.0_ProductIdsCharacteristic": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "urn_bamm_io.catenax.pcf_2.0.0_DeclaredUnit": { + "type": "string", + "enum": [ + "liter", + "kilogram", + "cubic meter", + "kilowatt hour", + "megajoule", + "ton kilometer", + "square meter" + ] + }, + "urn_bamm_io.catenax.pcf_2.0.0_StrictlyPositiveDecimal": { + "type": "number" + }, + "urn_bamm_io.catenax.pcf_2.0.0_EmissionsTrait": { + "type": "number", + "minimum": 0, + "exclusiveMinimum": false + }, + "urn_bamm_io.catenax.pcf_2.0.0_BiogenicEmissionEntity": { + "type": "object", + "properties": { + "landUseEmissions": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_EmissionsTrait" + }, + "otherEmissions": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_EmissionsTrait" + }, + "landUseChangeEmissions": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_EmissionsTrait" + } + } + }, + "urn_bamm_io.catenax.pcf_2.0.0_PrimaryDataShareTrait": { + "type": "number", + "maximum": 100, + "exclusiveMaximum": false, + "minimum": 0, + "exclusiveMinimum": false + }, + "urn_bamm_io.catenax.pcf_2.0.0_EmissionFactorSourcesEntity": { + "type": "object", + "properties": { + "name": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_NonEmptyString" + }, + "version": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_NonEmptyString" + } + }, + "required": [ + "name", + "version" + ] + }, + "urn_bamm_io.catenax.pcf_2.0.0_EmissionFactorSourcesCharacteristic": { + "type": "array", + "items": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_EmissionFactorSourcesEntity" + }, + "uniqueItems": true + }, + "urn_bamm_io.catenax.pcf_2.0.0_GeographyCountrySubdivisionTrait": { + "type": "string", + "pattern": "([A-Z]{2}-[A-Z0-9]{1,3}|)" + }, + "urn_bamm_io.catenax.pcf_2.0.0_GeographyCountryTrait": { + "type": "string", + "pattern": "([A-Z]{2})" + }, + "urn_bamm_io.catenax.pcf_2.0.0_GeographyRegionOrSubregionCharacteristic": { + "type": "string", + "enum": [ + "Africa", + "Americas", + "Asia", + "Europe", + "Oceania", + "Australia and New Zealand", + "Central Asia", + "Eastern Asia", + "Eastern Europe", + "Latin America and the Caribbean", + "Melanesia", + "Micronesia", + "Northern Africa", + "Northern America", + "Northern Europe", + "Polynesia", + "South-eastern Asia", + "Southern Asia", + "Southern Europe", + "Sub-Saharan Africa", + "Western Asia", + "Western Europe" + ] + }, + "urn_bamm_io.catenax.pcf_2.0.0_CrossSectoralStandardsUsedEnumerationCharacteristic": { + "type": "string", + "enum": [ + "GHG Protocol Product standard", + "ISO Standard 14067", + "ISO Standard 14044" + ] + }, + "urn_bamm_io.catenax.pcf_2.0.0_CrossSectoralStandardEntity": { + "type": "object", + "properties": { + "crossSectoralStandard": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_CrossSectoralStandardsUsedEnumerationCharacteristic" + } + }, + "required": [ + "crossSectoralStandard" + ] + }, + "urn_bamm_io.catenax.pcf_2.0.0_CrossSectoralStandardsUsedListCharacteristic": { + "type": "array", + "items": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_CrossSectoralStandardEntity" + } + }, + "urn_bamm_io.catenax.pcf_2.0.0_ProductOrSectorSpecificRuleOperator": { + "type": "string", + "enum": [ + "PEF", + "EPD International", + "Other" + ] + }, + "urn_bamm_io.catenax.pcf_2.0.0_RuleNamesTrait": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true, + "minItems": 1 + }, + "urn_bamm_io.catenax.pcf_2.0.0_ProductOrSectorSpecificRulesEntity": { + "type": "object", + "properties": { + "operator": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_ProductOrSectorSpecificRuleOperator" + }, + "ruleNames": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_RuleNamesTrait" + }, + "otherOperatorName": { + "$ref": "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Text" + } + }, + "required": [ + "operator", + "ruleNames" + ] + }, + "urn_bamm_io.catenax.pcf_2.0.0_ProductOrSectorSpecificRuleSet": { + "type": "array", + "items": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_ProductOrSectorSpecificRulesEntity" + }, + "uniqueItems": true + }, + "urn_bamm_io.catenax.pcf_2.0.0_PcfEntity": { + "type": "object", + "properties": { + "declaredUnit": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_DeclaredUnit" + }, + "unitaryProductAmount": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_StrictlyPositiveDecimal" + }, + "fossilGhgEmissions": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_EmissionsTrait" + }, + "biogenicEmissions": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_BiogenicEmissionEntity" + }, + "biogenicCarbonContent": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_EmissionsTrait" + }, + "reportingPeriodStart": { + "$ref": "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Timestamp" + }, + "reportingPeriodEnd": { + "$ref": "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Timestamp" + }, + "primaryDataShare": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_PrimaryDataShareTrait" + }, + "emissionFactorSources": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_EmissionFactorSourcesCharacteristic" + }, + "geographyCountrySubdivision": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_GeographyCountrySubdivisionTrait" + }, + "geographyCountry": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_GeographyCountryTrait" + }, + "geographyRegionOrSubregion": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_GeographyRegionOrSubregionCharacteristic" + }, + "boundaryProcessesDescription": { + "$ref": "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Text" + }, + "crossSectoralStandardsUsed": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_CrossSectoralStandardsUsedListCharacteristic" + }, + "productOrSectorSpecificRules": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_ProductOrSectorSpecificRuleSet" + }, + "allocationRulesDescription": { + "$ref": "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Text" + } + }, + "required": [ + "declaredUnit", + "unitaryProductAmount", + "fossilGhgEmissions", + "biogenicCarbonContent", + "reportingPeriodStart", + "reportingPeriodEnd", + "primaryDataShare", + "crossSectoralStandardsUsed", + "productOrSectorSpecificRules" + ] + } + } + }, + "properties": { + "id": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_IdTrait" + }, + "specVersion": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_SpecVersionTrait" + }, + "version": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_ProductFootprintVersionCharacteristic" + }, + "updated": { + "$ref": "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Timestamp" + }, + "companyName": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_NonEmptyString" + }, + "companyIds": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_CompanyIdsCharacteristic" + }, + "productDescription": { + "$ref": "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Text" + }, + "productIds": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_ProductIdsCharacteristic" + }, + "productCategoryCpc": { + "$ref": "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Text" + }, + "productNameCompany": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_NonEmptyString" + }, + "comment": { + "$ref": "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Text" + }, + "pcf": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.pcf_2.0.0_PcfEntity" + }, + "created": { + "$ref": "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Timestamp" + } + }, + "required": [ + "id", + "specVersion", + "version", + "companyName", + "companyIds", + "productDescription", + "productIds", + "productCategoryCpc", + "productNameCompany", + "comment", + "pcf", + "created" + ] +} +``` + +An exemplary payload JSON looks like this: + +```json +{ + "specVersion": "1.0.0", + "companyIds": [ + "urn:uuid:51131FB5-42A2-4267-A402-0ECFEFAD1619" + ], + "created": "2022-05-22T21:47:32Z", + "companyName": "My Corp", + "version": 42, + "productCategoryCpc": "3342", + "pcf": { + "geographyRegionOrSubregion": "Africa", + "emissionFactorSources": [ + { + "name": "Ecoinvent", + "version": "1.2.3" + } + ], + "fossilGhgEmissions": 4.1129383E36, + "biogenicCarbonContent": 0, + "geographyCountry": "DE", + "boundaryProcessesDescription": "End-of-life included", + "geographyCountrySubdivision": "US-NY", + "allocationRulesDescription": "Physical allocation. Mass of different outputs used.", + "biogenicEmissions": { + "landUseEmissions": 0.001, + "landUseChangeEmissions": 200.3, + "otherEmissions": 0 + }, + "primaryDataShare": 56.12, + "productOrSectorSpecificRules": [ + { + "operator": "PEF", + "ruleNames": "ABC 2021", + "otherOperatorName": "NSF" + } + ], + "crossSectoralStandardsUsed": [ + { + "crossSectoralStandard": "GHG Protocol Product standard" + } + ], + "reportingPeriodStart": "2021-01-01T00:00:00Z", + "reportingPeriodEnd": "2022-01-01T00:00:00Z", + "unitaryProductAmount": 1000, + "declaredUnit": "liter" + }, + "productNameCompany": "Green Ethanol Volnay", + "productIds": [ + "urn:gtin:4712345060507" + ], + "comment": "Comment for version 42.", + "id": "3893bb5d-da16-4dc1-9185-11d97476c254", + "updated": "2022-05-22T21:47:35Z", + "productDescription": "Cote’d Or Ethanol" +} +``` + +### 3.2 Properties & Entities + +The corresponding TTL-file for the aspect model can be accessed via the following link: + +[Semantic Hub - PCF Aspect Model](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.pcf/2.0.0/Pcf.ttl) + +In addition to the technical representation of the semantic model through the linked TTL-file, the file can also be imported into the official BAMM Aspect Model Editor for further use. For example, the actual aspect model can be visually displayed or an HTML documentation can be generated, encompassing all properties and entities in a table-like form. + +The BAMM Aspect Model Editor is open source and can be downloaded via the official website: [BAMM Aspect Model Editor Landing Page](https://www.bosch-connected-industry.com/de/de/downloads/aspect-model-editor) + +The official documentation and installation instructions can be accessed via the open manufacturing platform: [BAMM Documentation](https://openmanufacturingplatform.github.io/sds-documentation/ame-guide/4.0.2/introduction.html). + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0027-ProductCarbonFootprintAspectModel/assets/CX-0027.svg b/docs/standards/CX-0027-ProductCarbonFootprintAspectModel/assets/CX-0027.svg new file mode 100644 index 000000000..43b967150 --- /dev/null +++ b/docs/standards/CX-0027-ProductCarbonFootprintAspectModel/assets/CX-0027.svg @@ -0,0 +1,2230 @@ + + + +AspectModel + + + +landUseChangeEmissionsProperty + + + + + + + +«Property» +landUseChangeEmissions + +preferredName: Land Use Change Emissions +description: Land use change emissions. As specified by WBCSD (World +   Business Council for Sustainable Development) this value +   must include direct land use change (dLUC) where available, +   otherwise statistical land use change (sLUC) can be used. If +   available, including indirect land use change (iLUC) to +   remain optional. +see: https://wbcsd.github.io/introduction/ +exampleValue: 200.3 + + + +EmissionsTraitCharacteristic + + + + + + + +EmissionsTraitCharacteristic + + + +landUseChangeEmissionsProperty->EmissionsTraitCharacteristic + + +characteristic + + + +EmissionCharacteristicCharacteristic + + + + + + + +«Characteristic» +EmissionCharacteristic + +preferredName: Emission Characteristic +description: Characteristic for defining emissions in context of a PCF +   (Product Carbon Footprint) as specified by the WBCSD (World +   Business Council for Sustainable Development) Pathfinder +   initiative. +dataType: float +see: https://wbcsd.github.io/introduction/ + + + +EmissionsTraitCharacteristic->EmissionCharacteristicCharacteristic + + +baseCharacteristic + + + +EmissionConstraintConstraint + + + + + + + +«Constraint» +EmissionConstraint + +preferredName: EmissionConstraint +description: Only positive emission values (>0) are valid +minValue: 0.0 +see: https://wbcsd.github.io/introduction/ +lowerBoundDefinition: AT_LEAST +upperBoundDefinition: LESS_THAN + + + +EmissionsTraitCharacteristic->EmissionConstraintConstraint + + +constraint + + + +EmissionUnit + + + + + + + +«Unit» +Emission + +symbol: kgCO2e/kg + + + +EmissionCharacteristicCharacteristic->EmissionUnit + + +unit + + + +ruleNamesProperty + + + + + + + +«Property» +ruleNames + +preferredName: Product or Sector Specific Rule Names +description: Product-specific or sector-specific set of rules used for +   calculating or allocating GHG (Greenhouse Gas) emissions +   applied from the specified operator. Property defined by the +   WBCSD (World Business Council for Sustainable Development) +   Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ +exampleValue: ABC 2021 + + + +RuleNamesTraitCharacteristic + + + + + + + +RuleNamesTraitCharacteristic + + + +ruleNamesProperty->RuleNamesTraitCharacteristic + + +characteristic + + + +RuleNamesConstraintConstraint + + + + + + + +«Constraint» +RuleNamesConstraint + +preferredName: Rule Names Constraint +description: Constraint for defining a non-empty set of non-empty rule +   names as specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +minValue: 1 +see: https://wbcsd.github.io/introduction/ + + + +RuleNamesTraitCharacteristic->RuleNamesConstraintConstraint + + +constraint + + + +RuleNamesCharacteristicCharacteristic + + + + + + + +«Characteristic + Collection» +RuleNamesCharacteristic + +preferredName: Rule Names Characteristic +description: Non-empty set of rules applied by the specified operator. +   Defined by the WBCSD (World Business Council for Sustainable +   Development) Pathfinder initiative. +ordered: false +allowDuplicates: false +see: https://wbcsd.github.io/introduction/ + + + +RuleNamesTraitCharacteristic->RuleNamesCharacteristicCharacteristic + + +baseCharacteristic + + + +NonEmptyStringCharacteristic + + + + + + + +«Characteristic» +NonEmptyString + +preferredName: Non Empty String +description: String that contains at least one character. +dataType: string + + + +RuleNamesCharacteristicCharacteristic->NonEmptyStringCharacteristic + + +element Characteristic + + + +PcfAspect + + + + + + + +«Aspect» +Pcf + +preferredName: Product (Carbon) Footprint +description: Normative: Each Product (Carbon) Footprint represents the +   carbon footprint of a product with values in accordance with +   the WBCSD (World Business Council for Sustainable +   Development)/ Pathfinder framework. Non-normative: Each +   Product Footprint relates to a specific product, identified +   by one or more product identifiers. The Product Footprint is +   modeled as a multi purpose container for product-specific +   factors. +see: https://wbcsd.github.io/introduction/ + + + +companyNameProperty + + + + + + + +«Property» +companyName + +preferredName: Company Name +description: Name of the company that is the ProductFootprint Data Owner. +see: https://wbcsd.github.io/introduction/ +exampleValue: My Corp + + + +PcfAspect->companyNameProperty + + +property (companyName) + + + +productFootprintVersionProperty + + + + + + + +«Property» +productFootprintVersion + +preferredName: Product Footprint Version +description: Whenever a data owner or a host system updates a product +   footprint it must set the version to be by strictly greater +   than the value of all preceding footprints. +see: https://wbcsd.github.io/introduction/ +exampleValue: 42 + + + +PcfAspect->productFootprintVersionProperty + + +property (version) + + + +specVersionProperty + + + + + + + +«Property» +specVersion + +preferredName: Product Footprint Specification Version +description: Version of the product footprint data specification. The +   value MUST be "1.0.0". Note: subsequent revisions of the +   product footprint data specification will update this value +   according to the rules of Semantic Versioning 2.0.0. +see: https://wbcsd.github.io/introduction/ +exampleValue: 1.0.0 + + + +PcfAspect->specVersionProperty + + +property (specVersion) + + + +companyIdsProperty + + + + + + + +«Property» +companyIds + +preferredName: Company IDs +description: CompanyIds with value the non-empty set of Uniform Resource +   Names (URN)2. Each value of this set is supposed to uniquely +   identify the ProductFootprint Data Owner. +see: https://wbcsd.github.io/introduction/ +exampleValue: urn:uuid:51131FB5-42A2-4267-A402-0ECFEFAD1619 + + + +PcfAspect->companyIdsProperty + + +property (companyIds) + + + +idProperty + + + + + + + +«Property» +id + +preferredName: Product Footprint Identifier +description: The product footprint identifier as specified by the WBCSD +   (World Business Council for Sustainable Development) +   Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ +exampleValue: 3893bb5d-da16-4dc1-9185-11d97476c254 + + + +PcfAspect->idProperty + + +property (id) + + + +productNameCompanyProperty + + + + + + + +«Property» +productNameCompany + +preferredName: Product Trade Name +description: Trade name of the product. +see: https://wbcsd.github.io/introduction/ +exampleValue: Green Ethanol Volnay + + + +PcfAspect->productNameCompanyProperty + + +property (productNameCompany) + + + +productDescriptionProperty + + + + + + + +«Property» +productDescription + +preferredName: Product Description +description: Free-form description of the product plus other information +   related to it such as production technology or packaging. +see: https://wbcsd.github.io/introduction/ +exampleValue: Cote’d Or Ethanol + + + +PcfAspect->productDescriptionProperty + + +property (productDescription) + + + +pcfProperty + + + + + + + +«Property» +pcf + +preferredName: PCF (Product Carbon Footprint) +description: A PCF (Product Carbon Footprint) represents the carbon +   footprint of a product and related data in accordance with +   the Pathfinder Framework. +see: https://wbcsd.github.io/introduction/ + + + +PcfAspect->pcfProperty + + +property (pcf) + + + +updatedProperty + + + + + + + +«Property» +updated + +preferredName: Updated +description: Timestamp of the product footprint update. A product +   footprint must not include this property if an update has +   never been performed. The timestamp must be in UTC +   (Universal Time Code). +see: https://wbcsd.github.io/introduction/ +exampleValue: 2022-05-22T21:47:35Z + + + +PcfAspect->updatedProperty + + +property (optional) (updated) + + + +commentProperty + + + + + + + +«Property» +comment + +preferredName: Comment +description: Additional information and instructions related to the +   calculation of the footprint, or other information which +   informs the ability to interpret, to audit or to verify the +   Product Footprint. +see: https://wbcsd.github.io/introduction/ +exampleValue: Comment for version 42. + + + +PcfAspect->commentProperty + + +property (comment) + + + +createdProperty + + + + + + + +«Property» +created + +preferredName: Validity Start +description: Timestamp of the creation of the Product Footprint. +see: https://wbcsd.github.io/introduction/ +exampleValue: 2022-05-22T21:47:32Z + + + +PcfAspect->createdProperty + + +property + + + +productIdsProperty + + + + + + + +«Property» +productIds + +preferredName: Product IDs +description: Each of the values in the set is supposed to uniquely +   identify the product. +see: https://wbcsd.github.io/introduction/ +exampleValue: urn:gtin:4712345060507 + + + +PcfAspect->productIdsProperty + + +property (productIds) + + + +productCategoryCpcProperty + + + + + + + +«Property» +productCategoryCpc + +preferredName: Product Category +description: UN (United Nations) Product Classification Code (CPC - +   Central Classification Code) 3 that the given product +   belongs to. +see: https://wbcsd.github.io/introduction/ +exampleValue: 3342 + + + +PcfAspect->productCategoryCpcProperty + + +property (productCategoryCpc) + + + +companyNameProperty->NonEmptyStringCharacteristic + + +characteristic + + + +ProductFootprintVersionCharacteristicCharacteristic + + + + + + + +«Characteristic» +ProductFootprintVersionCharacteristic + +preferredName: Product Footprint Version Characteristic +description: Characteristic for defining a product footprint version as +   specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +dataType: positiveInteger +see: https://wbcsd.github.io/introduction/ + + + +productFootprintVersionProperty->ProductFootprintVersionCharacteristicCharacteristic + + +characteristic + + + +SpecVersionTraitCharacteristic + + + + + + + +SpecVersionTraitCharacteristic + + + +specVersionProperty->SpecVersionTraitCharacteristic + + +characteristic + + + +TextCharacteristic + + + + + + + +«Characteristic» +Text + +preferredName: Text +description: Describes a Property which contains plain text. This is +   intended exclusively for human readable strings, not for +   identifiers, measurement values, etc. +dataType: string + + + +SpecVersionTraitCharacteristic->TextCharacteristic + + +baseCharacteristic + + + +VersionConstraintConstraint + + + + + + + +«Constraint» +VersionConstraint + +preferredName: Version Constraint +description: Constraint for defining a version of an artefact (e.g. a +   specification version) belonging to a product footprint as +   specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +value: \d+\.\d+\.\d+ +see: https://wbcsd.github.io/introduction/ + + + +SpecVersionTraitCharacteristic->VersionConstraintConstraint + + +constraint + + + +CompanyIdsCharacteristicCharacteristic + + + + + + + +«Characteristic + Collection» +CompanyIdsCharacteristic + +preferredName: Company IDs Characteristic +description: Characteristic for defining a list of company ids in context +   of a product footprint. +dataType: string +ordered: false +allowDuplicates: false +see: https://wbcsd.github.io/introduction/ + + + +companyIdsProperty->CompanyIdsCharacteristicCharacteristic + + +characteristic + + + +IdTraitCharacteristic + + + + + + + +IdTraitCharacteristic + + + +idProperty->IdTraitCharacteristic + + +characteristic + + + +IdCharacteristicCharacteristic + + + + + + + +«Characteristic» +IdCharacteristic + +preferredName: ID Characteristic +description: Characteristic for defining a product footprint identifier +   as specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +dataType: string +see: https://wbcsd.github.io/introduction/ + + + +IdTraitCharacteristic->IdCharacteristicCharacteristic + + +baseCharacteristic + + + +IdConstraintConstraint + + + + + + + +«Constraint» +IdConstraint + +preferredName: ID Constraint +description: Constraint for defining a product footprint identifier as +   specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +value: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ +see: https://wbcsd.github.io/introduction/ + + + +IdTraitCharacteristic->IdConstraintConstraint + + +constraint + + + +productNameCompanyProperty->NonEmptyStringCharacteristic + + +characteristic + + + +productDescriptionProperty->TextCharacteristic + + +characteristic + + + +PcfCharacteristicCharacteristic + + + + + + + +«Characteristic» +PcfCharacteristic + +preferredName: PCF (Product Carbon Footprint) Characteristic +description: Characteristic for defining a PCF (Product Carbon Footprint) +   as specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ + + + +pcfProperty->PcfCharacteristicCharacteristic + + +characteristic + + + +PcfEntityEntity + + + + + + + +«Entity» +PcfEntity + +preferredName: PCF (Product Carbon Footprint) Entity +description: Entity for defining a PCF (Product Carbon Footprint) as +   specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ + + + +PcfCharacteristicCharacteristic->PcfEntityEntity + + +dataType + + + +productOrSectorSpecificRulesProperty + + + + + + + +«Property» +productOrSectorSpecificRules + +preferredName: Product or Sector Specific Rules +description: Product or sector specific rules applied for calculating or +   allocating GHG (Greenhouse Gas) emissions, e.g. PCRs +   (Product Category Rules), including operators or pubishers +   and according rule names. Specified by the WBCSD (World +   Business Council for Sustainable Development) Pathfinder +   initiative. +see: https://wbcsd.github.io/introduction/ + + + +PcfEntityEntity->productOrSectorSpecificRulesProperty + + +property (productOrSectorSpecificRules) + + + +unitaryProductAmountProperty + + + + + + + +«Property» +unitaryProductAmount + +preferredName: Package size of referred product +description: Amount of units contained within the product the PCF +   (Product Carbon Footprint) is referring to. +see: https://wbcsd.github.io/introduction/ +exampleValue: 1000.0 + + + +PcfEntityEntity->unitaryProductAmountProperty + + +property (unitaryProductAmount) + + + +fossilGhgEmissionsProperty + + + + + + + +«Property» +fossilGhgEmissions + +preferredName: Fossil Emissions +description: Emissions from the combustion of fossil sources. +see: https://wbcsd.github.io/introduction/ + + + +PcfEntityEntity->fossilGhgEmissionsProperty + + +property (fossilGhgEmissions) + + + +crossSectoralStandardsUsedProperty + + + + + + + +«Property» +crossSectoralStandardsUsed + +preferredName: Cross Sectoral Standards Used +description: Discloses the cross-sectoral standards applied for +   calculating or allocating GHG (Greenhouse Gas) emissions as +   specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ + + + +PcfEntityEntity->crossSectoralStandardsUsedProperty + + +property (crossSectoralStandardsUsed) + + + +declaredUnitProperty + + + + + + + +«Property» +declaredUnit + +preferredName: Unit of measurement +description: unit of analysis of the product. +see: https://wbcsd.github.io/introduction/ + + + +PcfEntityEntity->declaredUnitProperty + + +property (declaredUnit) + + + +primaryDataShareProperty + + + + + + + +«Property» +primaryDataShare + +preferredName: Primary Data Share +description: Share of primary data. +see: https://wbcsd.github.io/introduction/ +exampleValue: 56.12 + + + +PcfEntityEntity->primaryDataShareProperty + + +property (primaryDataShare) + + + +geographyCountryProperty + + + + + + + +«Property» +geographyCountry + +preferredName: Country +description: Two letter country code. Value must conform to data type ISO +   3166CC as specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ +exampleValue: DE + + + +PcfEntityEntity->geographyCountryProperty + + +property (optional) (geographyCountry) + + + +biogenicEmissionsProperty + + + + + + + +«Property» +biogenicEmissions + +preferredName: Summary of land (change) emissions +description: Biogenic emission factors. +see: https://wbcsd.github.io/introduction/ + + + +PcfEntityEntity->biogenicEmissionsProperty + + +property (optional) (biogenicEmissions) + + + +geographyRegionOrSubregionProperty + + + + + + + +«Property» +geographyRegionOrSubregion + +preferredName: Region +description: Region according to list as specified by the WBCSD (World +   Business Council for Sustainable Development) Pathfinder +   initiative. +see: https://wbcsd.github.io/introduction/ + + + +PcfEntityEntity->geographyRegionOrSubregionProperty + + +property (optional) (geographyRegionOrSubregion) + + + +emissionFactorSourcesProperty + + + + + + + +«Property» +emissionFactorSources + +preferredName: Emission Factor Data Sources +description: Emission factor databases accepted under Version 1 of the +   Pathfinder Framework (see the Pathfinder Framework Section +   6.2). +see: https://wbcsd.github.io/introduction/ + + + +PcfEntityEntity->emissionFactorSourcesProperty + + +property (optional) (emissionFactorSources) + + + +allocationRulesDescriptionProperty + + + + + + + +«Property» +allocationRulesDescription + +preferredName: Allocation Rules Used +description: Allocation rules used and underlying reasoning as specified +   by the WBCSD (World Business Council for Sustainable +   Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ +exampleValue: Physical allocation. Mass of different outputs used. + + + +PcfEntityEntity->allocationRulesDescriptionProperty + + +property (optional) (allocationRulesDescription) + + + +reportingPeriodStartProperty + + + + + + + +«Property» +reportingPeriodStart + +preferredName: Reporting Period (Start) +description: Starting timestamp for the time scope of a PCF (Product +   Carbon Footprint). +see: https://wbcsd.github.io/introduction/ +exampleValue: 2021-01-01T00:00:00Z + + + +PcfEntityEntity->reportingPeriodStartProperty + + +property (reportingPeriodStart) + + + +geographyCountrySubdivisionProperty + + + + + + + +«Property» +geographyCountrySubdivision + +preferredName: Subdivision +description: Subdivision of a country. Value must be an ISO 3166-2 +   subdivision code as specified by the WBCSD (World Business +   Council for Sustainable Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ +exampleValue: US-NY + + + +PcfEntityEntity->geographyCountrySubdivisionProperty + + +property (optional) (geographyCountrySubdivision) + + + +boundaryProcessesDescriptionProperty + + + + + + + +«Property» +boundaryProcessesDescription + +preferredName: Process Description +description: Processes attributable to each lifecycle stage as specified +   by the WBCSD (World Business Council for Sustainable +   Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ +exampleValue: End-of-life included + + + +PcfEntityEntity->boundaryProcessesDescriptionProperty + + +property (optional) (boundaryProcessesDescription) + + + +biogenicCarbonContentProperty + + + + + + + +«Property» +biogenicCarbonContent + +preferredName: Biogenic Carbon Content +description: Mass of biogenic carbon per given unit of exchange. +see: https://wbcsd.github.io/introduction/ +exampleValue: 0.0 + + + +PcfEntityEntity->biogenicCarbonContentProperty + + +property (biogenicCarbonContent) + + + +reportingPeriodEndProperty + + + + + + + +«Property» +reportingPeriodEnd + +preferredName: Reporting Period (End excl.) +description: Ending timestamp for the time scope of a product footprint +   as specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ +exampleValue: 2022-01-01T00:00:00Z + + + +PcfEntityEntity->reportingPeriodEndProperty + + +property (reportingPeriodEnd) + + + +ProductOrSectorSpecificRuleSetCharacteristic + + + + + + + +«Characteristic + Collection» +ProductOrSectorSpecificRuleSet + +preferredName: Product Or Sector Specific Rules Set +description: Characteristic for defining the set of product or sector +   specific rules of a product carbon footprint as specified by +   the WBCSD (World Business Council for Sustainable +   Development) Pathfinder initiative. +ordered: false +allowDuplicates: false +see: https://wbcsd.github.io/introduction/ + + + +productOrSectorSpecificRulesProperty->ProductOrSectorSpecificRuleSetCharacteristic + + +characteristic + + + +ProductOrSectorSpecificRulesEntityEntity + + + + + + + +«Entity» +ProductOrSectorSpecificRulesEntity + +preferredName: Product Or Sector Specific Rules Entity +description: Entity for defining the set of values for the product or +   sector specific rules of a product carbon footprint as +   specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ + + + +ProductOrSectorSpecificRuleSetCharacteristic->ProductOrSectorSpecificRulesEntityEntity + + +dataType + + + +ProductOrSectorSpecificRulesEntityEntity->ruleNamesProperty + + +property (ruleNames) + + + +otherOperatorNameProperty + + + + + + + +«Property» +otherOperatorName + +preferredName: Other Operator or Publisher of Sector Specific Rules +description: Other operator of PCR (Product Category Rule)/ PSR (Product +   Specific Rule) as specified by the WBCSD (World Business +   Council for Sustainable Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ +exampleValue: NSF + + + +ProductOrSectorSpecificRulesEntityEntity->otherOperatorNameProperty + + +property (optional) (otherOperatorName) + + + +operatorProperty + + + + + + + +«Property» +operator + +preferredName: Operator or Publisher of Sector Specific Rules +description: Operator of PCR (Product Category Rule)/ PSR (Product +   Specific Rule) as specified by the WBCSD (World Business +   Council for Sustainable Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ + + + +ProductOrSectorSpecificRulesEntityEntity->operatorProperty + + +property (operator) + + + +otherOperatorNameProperty->TextCharacteristic + + +characteristic + + + +ProductOrSectorSpecificRuleOperatorCharacteristic + + + + + + + +«Characteristic + Enumeration» +ProductOrSectorSpecificRuleOperator + +preferredName: Product Or Sector Specific Rule Operator +description: Enumeration of PCR (Product Category Rule) operators as +   specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +dataType: xsd:string +values: PEF, EPD International, Other +see: https://wbcsd.github.io/introduction/ + + + +operatorProperty->ProductOrSectorSpecificRuleOperatorCharacteristic + + +characteristic + + + +StrictlyPositiveDecimalCharacteristic + + + + + + + +«Characteristic» +StrictlyPositiveDecimal + +preferredName: Strictly Positive Decimal +description: A positive, non-zero decimal. +dataType: float + + + +unitaryProductAmountProperty->StrictlyPositiveDecimalCharacteristic + + +characteristic + + + +fossilGhgEmissionsProperty->EmissionsTraitCharacteristic + + +characteristic + + + +CrossSectoralStandardsUsedListCharacteristicCharacteristic + + + + + + + +«Characteristic + Collection» +CrossSectoralStandardsUsedListCharacteristic + +preferredName: Cross Sectoral Standards Used Characteristic +description: Characteristic for defining the list of valid accounting +   standards used for product carbon footprint calculation as +   specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +ordered: true +allowDuplicates: true +see: https://wbcsd.github.io/introduction/ + + + +crossSectoralStandardsUsedProperty->CrossSectoralStandardsUsedListCharacteristicCharacteristic + + +characteristic + + + +CrossSectoralStandardEntityEntity + + + + + + + +«Entity» +CrossSectoralStandardEntity + +preferredName: Cross Sectoral Standard Entity +description: Entity for defining an accounting standard used for product +   carbon footprint calculation as specified by the WBCSD +   (World Business Council for Sustainable Development) +   Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ + + + +CrossSectoralStandardsUsedListCharacteristicCharacteristic->CrossSectoralStandardEntityEntity + + +dataType + + + +crossSectoralStandardProperty + + + + + + + +«Property» +crossSectoralStandard + +preferredName: Cross Sectoral Standard +description: Discloses a cross-sectoral standard applied for calculating +   or allocating GHG (Greenhouse Gas) emissions as specified by +   the WBCSD (World Business Council for Sustainable +   Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ + + + +CrossSectoralStandardEntityEntity->crossSectoralStandardProperty + + +property (crossSectoralStandard) + + + +CrossSectoralStandardsUsedEnumerationCharacteristicCharacteristic + + + + + + + +«Characteristic + Enumeration» +CrossSectoralStandardsUsedEnumerationCharacteristic + +preferredName: Cross Sectoral Standards Used Enumeration Characteristic +description: Characteristic for defining the enumeration of valid +   accounting standards used for product carbon footprint +   calculation as specified by the WBCSD (World Business +   Council for Sustainable Development) Pathfinder initiative. +dataType: xsd:string +values: GHG Protocol Product standard, ISO Standard 14067, ISO +   Standard 14044 +see: https://wbcsd.github.io/introduction/ + + + +crossSectoralStandardProperty->CrossSectoralStandardsUsedEnumerationCharacteristicCharacteristic + + +characteristic + + + +DeclaredUnitCharacteristic + + + + + + + +«Characteristic + Enumeration» +DeclaredUnit + +preferredName: Unit of Measurement +description: Unit of analysis of the product with accepted values as +   specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +dataType: xsd:string +values: liter, kilogram, cubic meter, kilowatt hour, megajoule, ton +   kilometer, square meter +see: https://wbcsd.github.io/introduction/ + + + +declaredUnitProperty->DeclaredUnitCharacteristic + + +characteristic + + + +PrimaryDataShareTraitCharacteristic + + + + + + + +PrimaryDataShareTraitCharacteristic + + + +primaryDataShareProperty->PrimaryDataShareTraitCharacteristic + + +characteristic + + + +PrimaryDataShareCharacteristicCharacteristic + + + + + + + +«Characteristic» +PrimaryDataShareCharacteristic + +preferredName: Primary Data Share Characteristic +description: Characteristic for defining the primary data share of a +   product footprint as specified by the WBCSD (World Business +   Council for Sustainable Development) Pathfinder initiative. +dataType: float +see: https://wbcsd.github.io/introduction/ + + + +PrimaryDataShareTraitCharacteristic->PrimaryDataShareCharacteristicCharacteristic + + +baseCharacteristic + + + +PrimaryDataShareConstraintConstraint + + + + + + + +«Constraint» +PrimaryDataShareConstraint + +preferredName: Primary Data Share Constraint +description: Constraint for a primary data share of a product footprint +   which limit values between 0.0 and 100.0 as specified by the +   WBCSD (World Business Council for Sustainable Development) +   Pathfinder initiative. +minValue: 0.0 +maxValue: 100.0 +see: https://wbcsd.github.io/introduction/ +lowerBoundDefinition: AT_LEAST +upperBoundDefinition: AT_MOST + + + +PrimaryDataShareTraitCharacteristic->PrimaryDataShareConstraintConstraint + + +constraint + + + +PercentUnit + + + + + + + +«Unit» +Percent + +symbol: % + + + +PrimaryDataShareCharacteristicCharacteristic->PercentUnit + + +unit + + + +GeographyCountryTraitCharacteristic + + + + + + + +GeographyCountryTraitCharacteristic + + + +geographyCountryProperty->GeographyCountryTraitCharacteristic + + +characteristic + + + +GeographyCountryTraitCharacteristic->TextCharacteristic + + +baseCharacteristic + + + +GeographyCountryConstraintConstraint + + + + + + + +«Constraint» +GeographyCountryConstraint + +preferredName: Country Constraint +description: Constraint for defining a geography country conform to ISO +   3166CC as specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +value: ([A-Z]{2}) +see: https://wbcsd.github.io/introduction/ + + + +GeographyCountryTraitCharacteristic->GeographyCountryConstraintConstraint + + +constraint + + + +BiogenicEmissionCharacteristicCharacteristic + + + + + + + +«Characteristic» +BiogenicEmissionCharacteristic + +preferredName: Biogenic Emission Characteristic +description: Characteristic for defining the biogenic emissions of a PCF +   (Product Carbon Footprint) as specified by the WBCSD (World +   Business Council for Sustainable Development) Pathfinder +   initiative. +see: https://wbcsd.github.io/introduction/ + + + +biogenicEmissionsProperty->BiogenicEmissionCharacteristicCharacteristic + + +characteristic + + + +BiogenicEmissionEntityEntity + + + + + + + +«Entity» +BiogenicEmissionEntity + +preferredName: Biogenic Emission Entity +description: Entity for biogenic emissions of a PCF (Product Carbon +   Footprint) as specified by the WBCSD (World Business Council +   for Sustainable Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ + + + +BiogenicEmissionCharacteristicCharacteristic->BiogenicEmissionEntityEntity + + +dataType + + + +BiogenicEmissionEntityEntity->landUseChangeEmissionsProperty + + +property (optional) (landUseChangeEmissions) + + + +landUseEmissionsProperty + + + + + + + +«Property» +landUseEmissions + +preferredName: Land Use Emissions +description: Land use emissions (e.g. cultural practice). +see: https://wbcsd.github.io/introduction/ +exampleValue: 0.001 + + + +BiogenicEmissionEntityEntity->landUseEmissionsProperty + + +property (optional) (landUseEmissions) + + + +otherEmissionsProperty + + + + + + + +«Property» +otherEmissions + +preferredName: Other Emissions +description: Other emissions (e.g. biogenic waste treatment). +see: https://wbcsd.github.io/introduction/ +exampleValue: 0.0 + + + +BiogenicEmissionEntityEntity->otherEmissionsProperty + + +property (optional) (otherEmissions) + + + +landUseEmissionsProperty->EmissionsTraitCharacteristic + + +characteristic + + + +otherEmissionsProperty->EmissionsTraitCharacteristic + + +characteristic + + + +GeographyRegionOrSubregionCharacteristicCharacteristic + + + + + + + +«Characteristic + Enumeration» +GeographyRegionOrSubregionCharacteristic + +preferredName: Region Characteristic +description: Characteristic for defining a list of valid regions as +   specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +dataType: xsd:string +values: Africa, Americas, Asia, Europe, Oceania, Australia and New +   Zealand, Central Asia, Eastern Asia, Eastern Europe, Latin +   America and the Caribbean, Melanesia, Micronesia, Northern +   Africa, Northern America, Northern Europe, Polynesia, +   South-eastern Asia, Southern Asia, Southern Europe, +   Sub-Saharan Africa, Western Asia, Western Europe +see: https://wbcsd.github.io/introduction/ + + + +geographyRegionOrSubregionProperty->GeographyRegionOrSubregionCharacteristicCharacteristic + + +characteristic + + + +EmissionFactorSourcesCharacteristicCharacteristic + + + + + + + +«Characteristic + Collection» +EmissionFactorSourcesCharacteristic + +preferredName: Emission Factor Sources Characteristic +description: Characteristic for defining a list of emission factor +   databases for a product footprint as specified by the WBCSD +   (World Business Council for Sustainable Development) +   Pathfinder initiative. +ordered: false +allowDuplicates: false +see: https://wbcsd.github.io/introduction/ + + + +emissionFactorSourcesProperty->EmissionFactorSourcesCharacteristicCharacteristic + + +characteristic + + + +EmissionFactorSourcesEntityEntity + + + + + + + +«Entity» +EmissionFactorSourcesEntity + +preferredName: Emission Factor Sources Entity +description: Entity for defining a list of emission factor databases for +   a product footprint incl. their names and versions as +   specified by the WBCSD (World Business Council for +   Sustainable Development) Pathfinder initiative. +see: https://wbcsd.github.io/introduction/ + + + +EmissionFactorSourcesCharacteristicCharacteristic->EmissionFactorSourcesEntityEntity + + +dataType + + + +nameProperty + + + + + + + +«Property» +name + +preferredName: Name of Secondary Data Source +description: Secondary data sources used (mandatory if applicable) and +   information on which life cycle stages the sources were used +   for. +see: https://wbcsd.github.io/introduction/ +exampleValue: Ecoinvent + + + +EmissionFactorSourcesEntityEntity->nameProperty + + +property (name) + + + +versionProperty + + + + + + + +«Property» +version + +preferredName: Version of Secondary Data Source +description: Secondary data sources version (mandatory if applicable). +see: https://wbcsd.github.io/introduction/ +exampleValue: 1.2.3 + + + +EmissionFactorSourcesEntityEntity->versionProperty + + +property (version) + + + +nameProperty->NonEmptyStringCharacteristic + + +characteristic + + + +versionProperty->NonEmptyStringCharacteristic + + +characteristic + + + +allocationRulesDescriptionProperty->TextCharacteristic + + +characteristic + + + +TimestampCharacteristic + + + + + + + +«Characteristic» +Timestamp + +preferredName: Timestamp +description: Describes a Property which contains the date and time with +   an optional timezone. +dataType: dateTime + + + +reportingPeriodStartProperty->TimestampCharacteristic + + +characteristic + + + +GeographyCountrySubdivisionTraitCharacteristic + + + + + + + +GeographyCountrySubdivisionTraitCharacteristic + + + +geographyCountrySubdivisionProperty->GeographyCountrySubdivisionTraitCharacteristic + + +characteristic + + + +GeographyCountrySubdivisionTraitCharacteristic->NonEmptyStringCharacteristic + + +baseCharacteristic + + + +GeographyCountrySubdivisionConstraintConstraint + + + + + + + +«Constraint» +GeographyCountrySubdivisionConstraint + +preferredName: Subdivision Constraint +description: Constraint for defining a geography country subdivision in +   compliance to ISO 3166-2 as specified by the WBCSD (World +   Business Council for Sustainable Development) Pathfinder +   initiative. +value: ([A-Z]{2}-[A-Z0-9]{1,3}|) +see: https://wbcsd.github.io/introduction/ + + + +GeographyCountrySubdivisionTraitCharacteristic->GeographyCountrySubdivisionConstraintConstraint + + +constraint + + + +boundaryProcessesDescriptionProperty->TextCharacteristic + + +characteristic + + + +biogenicCarbonContentProperty->EmissionsTraitCharacteristic + + +characteristic + + + +reportingPeriodEndProperty->TimestampCharacteristic + + +characteristic + + + +updatedProperty->TimestampCharacteristic + + +characteristic + + + +commentProperty->TextCharacteristic + + +characteristic + + + +createdProperty->TimestampCharacteristic + + +characteristic + + + +ProductIdsCharacteristicCharacteristic + + + + + + + +«Characteristic + Collection» +ProductIdsCharacteristic + +preferredName: Product IDs Characteristic +description: Characteristic for defining a lost of product ids in context +   of a product footprint. +dataType: string +ordered: false +allowDuplicates: false +see: https://wbcsd.github.io/introduction/ + + + +productIdsProperty->ProductIdsCharacteristicCharacteristic + + +characteristic + + + +productCategoryCpcProperty->TextCharacteristic + + +characteristic + + + diff --git a/docs/standards/CX-0029-ProductCarbonFootprintRulebook/CX-0029-ProductCarbonFootprintRulebook-v2.0.0.pdf b/docs/standards/CX-0029-ProductCarbonFootprintRulebook/CX-0029-ProductCarbonFootprintRulebook-v2.0.0.pdf new file mode 100644 index 000000000..6581379b7 Binary files /dev/null and b/docs/standards/CX-0029-ProductCarbonFootprintRulebook/CX-0029-ProductCarbonFootprintRulebook-v2.0.0.pdf differ diff --git a/docs/standards/CX-0030-DataModelBoMAsSpecified/CX-0030-DataModelBoMAsSpecified.md b/docs/standards/CX-0030-DataModelBoMAsSpecified/CX-0030-DataModelBoMAsSpecified.md new file mode 100644 index 000000000..fee82a896 --- /dev/null +++ b/docs/standards/CX-0030-DataModelBoMAsSpecified/CX-0030-DataModelBoMAsSpecified.md @@ -0,0 +1,235 @@ +# CX-0030 Aspect Model BoM As Specified v2.0.0 + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +> *Relevant only for existing standards. At the new standard, please delete* + +## ABSTRACT + +A core problem of the circular economy is making the right decisions. These strategies include Rethink, Refuse, Reduce, Reuse, Refurbish, Redesign, Recycle, Recover and Rot. +In particular, the end of life (EoL) decisions are a challenge. In order for a circular economy to scale, however, these must be supported in a standardized way. The present data model is used for this purpose. This supports the products R-Strategy Assistant & Circularity Dashboard to provide decision support for its users. In this first scope, the model should support the EoL decisions in particular. +The data provided by the data provider allows relevant decisions to be derived. This leads to higher reuse and recycling rates, an economically and ecologically balanced decision-making process and a scaled circular economy. + +## 1 INTRODUCTION + +The SingleLevelBoMAsSpecified defines the view of the OEM or producer of the whole product, e.g. the OEM of a vehicle. It is free of any supplier-related information and specifies the promised and guaranteed content of the whole product to the end customer. +This “top-down” view contrasts with the “bottom-up” view of the SingleLevelBoMAsPlanned, though several sub-aspects are shared. The SingleLevelBoMAsSpecified is merely one aspect, which is attached to the twin of the whole product and itself does neither introduce further twins nor reference them. Instead, it merely comprises all functional information required by dismantlers, workshops, or requestors for used parts to search for and to make a match on the marketplace. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +- Data Provider / Consumer + +The purpose of this document is the description of the Asset Administration Shell submodel bill of material (BoM) as specified. It defines the view of the producing company of the produced product. The presented data model is described and illustrated in the following with the entities and properties and their interrelationships. +This chapter serves to situate the given reference implementation, to outline its prerequisites and to point out its limitations. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +There are several parties needing information about the product, be it dismantlers, workshops or the owners. With the aspect model "as Planned" there is already a model which contains interesting information for these groups. However, this model also reveals sensitive information about the manufacturer, for example supplier relationships. This creates a conflict between the need for information of the exploiting/using parties and the data sovereignty of the manufacturer. This conflict is solved by the given aspect model "BoMAsSpecified" by providing a top-down view of the product and its components. Together with the aspect model "PartAsSpecified", "BomAsSpecified" provides an abstraction layer for other Catena-X members to obtain relevant information about the product while protecting sensitive information of the manufacturer. + +Standarts which are not required but may be interesting to the use case: + +- [CX - 0032 Part As Specified](https://catena-x.net/de/standard-library) + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +### 1.4 EXAMPLES + +```json +{ + "manufacturerId": "BPNL1234567890LR", + "assetId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d", + "childItems": [ + { + "childItemCategory": "e.g. vehicle, winter wheels, bicycle rack", + "item": [ + { + "itemClassification": [ + { + "value": "STEEWHL", + "key": "BMW:PartFamily" + } + ], + "itemQuantity": { + "quantityNumber": 350.0, + "measurementUnit": "unit:kW" + }, + "ownerItemId": "urn:uuid:b4741433-92bb-4027-9a02-bbc64a58d193", + "itemVersion": "05", + "itemDescription": "The steering wheel is nice and round", + "createdOn": "2022-02-03T14:48:54.709Z", + "itemPositioning": "left", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + } + ], + "childassetId": "urn:uuid:218b26f4-4a0b-4a7f-b2c1-d248927718bf " + } + ] +} +``` + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +The following terms are especially relevant for the understanding of the standard: + +Business Partner Number (BPN) +: A BPN is the unique identifier of a partner within Catena-x + +End of life vehicle (EoL vehicle) +: 'End-of life vehicle' means a vehicle which is waste within the meaning of Article 1(a) of Directive 75/442/EEC on waste (waste means any substance or object which the holder disposes of or is required to dispose of pursuant to the provisions of national law in force). + +Original Equipment Manufacturer (OEM) +:An original equipment manufacturer (OEM) is generally perceived as a company that produces non-aftermarket parts and equipment that may be marketed by another manufacturer. + +Bill of material (BOM) +:A bill of material is a list of the raw materials, sub-assemblies, intermediate assemblies, sub-components, parts, and the quantities of each needed to manufacture an end product. + +Eclipse Dataspace Connector (EDC) +:The Eclipse Dataspace Connector provides a framework for sovereign, inter-organizational data exchange. + +## 2 ASPECT MODEL "Single Level BoM As Specified" + +> *This section is normative* + +### 2.1 INTRODUCTION + +The purpose of this document is the description of the Asset Administration Shell submodel SingleLevelBoMAsSpecified. It defines Bill of Material and all relevant attributes. The presented data model is described and illustrated in the following with the entities and properties and their interrelationships. + +Every data provider **MUST** provide the data +conformant to the semantic model specified in this document. + +The unique identifier of the semantic model specified in this document +**MUST** be used by the data provider to define the semantics of the data +being transferred. + +Every certified business application using the Single Level BoM As Specified data **MUST** +be able to consume data conformant to the semantic model specified in +this document. + +This semantic model **MUST** be made available in the central Semantic Hub. + +Data consumers and data provider **MUST** comply with the license of the +semantic model. + +In the Catena-X data space Single Level BoM As Specified data **MUST** be requested and +exchanged via Eclipse Dataspace Connector (EDC) conformant to [CX-0018](#31-normative-references) +and [CX-0002](#31-normative-references). + +The JSON Payload of data providers MUST be conformant to the JSON Schema +as specified in this document. + +### 2.2 SPECIFICATION ARTIFACTS + +The modelling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#32-non-normative-references). + +This aspect model is written in BAMM 2.0.0 as a modeling language conformant to CX-0003 as input for the semantic deriven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub2F2F conformant to CX-0003. + +### 2.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group Digital Product Pass (DPP).This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons4F4F. + +### 2.4 IDENTIFER OF SEMANTIC MODEL + +The semantic model has the unique identifier: + +```text +urn:samm:io.catenax.single_level_bom_as_specified:2.0.0##SingleLevelBomAsSpecified +``` + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +### 2.5 FORMATS OF SEMANTIC MODEL + +All different formats of the semantic model can be found in the github repository. + +- [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_specified/2.0.0](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_specified/2.0.0) + +#### 2.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + +- [https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_bom_as_specified/2.0.0/SingleLevelBomAsSpecified.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_bom_as_specified/2.0.0/SingleLevelBomAsSpecified.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +- [https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_specified/2.0.0/gen](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_specified/2.0.0/gen) + +#### 2.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +- [https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_bom_as_specified/2.0.0/gen/SingleLevelBomAsSpecified.json](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_bom_as_specified/2.0.0/gen/SingleLevelBomAsSpecified.json) + +#### 2.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#32-non-normative-references)]. + +Note: As soon as the specification V3.0 of the Asset Administration Shell specfication is available +an update will be provided. + +### 2.6 SEMANTIC MODEL + +The data model is described in SAMM . A html documentation can be generated from the rdf turtle +file. + +So far no .md documentation can be generated. So it is recommended to not + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +- [CX-0003 BAMM Aspect Meta Model v1.0.2](https://catena-x.net/de/standard-library) +- [CX-0002 Digital Twins in Catena - X v2.0.0](https://catena-x.net/de/standard-library) +- [CX-0018 Sovereign Data Exchange (EDC) v2.0.1](https://catena-x.net/de/standard-library) + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +```text + [Optional] – Links to further documentation that may help to understand the + standard but isn’t relevant for conformity assessment +``` + +[SMT] How to create a submodel template specification. Guideline. Download from: [https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf) + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +## ANNEXES + +### FIGURES + +> *This section is non-normative* +![SingleLevelBoMAsSpecified_2.0.0](./assets/SingleLevelBomAsSpecified_2_0_0.svg) + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0030-DataModelBoMAsSpecified/assets/SingleLevelBomAsSpecified_2_0_0.svg b/docs/standards/CX-0030-DataModelBoMAsSpecified/assets/SingleLevelBomAsSpecified_2_0_0.svg new file mode 100644 index 000000000..32baef53f --- /dev/null +++ b/docs/standards/CX-0030-DataModelBoMAsSpecified/assets/SingleLevelBomAsSpecified_2_0_0.svg @@ -0,0 +1,946 @@ + + + +AspectModel + + + +ChildItemCharacteristicCharacteristic + + + + + + + +«Characteristic + Collection» +ChildItemCharacteristic + +preferredName: Child Item Characteristic +description: The characteristic of the child item property +ordered: false +allowDuplicates: false + + + +ChildItemEntityEntity + + + + + + + +«Entity» +ChildItemEntity + +preferredName: Child Item Entity +description: Encapsulates the properties describing the child item + + + +ChildItemCharacteristicCharacteristic->ChildItemEntityEntity + + +dataType + + + +childItemCategoryProperty + + + + + + + +«Property» +childItemCategory + +preferredName: Child Item Category +description: The BomAsSpecified defines the view of the OEM or producer +   of the whole product, e.g. the OEM of a vehicle. It is free +   of any supplier-related information and specifies the +   promised and guaranteed content of the whole product to the +   end customer. This "top-down" view is in contrast to the +   "bottom-up" view of the SingleLevelBoMAsPlanned, though +   several sub-aspects are shared. The BomAsSpecified is merely +   one aspect, which is attached to the twin of the whole +   product and itself does neither introduce further twins nor +   reference them. Instead it merely comprises all functional +   information required by dismantlers, workshops or requestors +   for used parts to search for and to make a match on the +   market place. +exampleValue: e.g. vehicle, winter wheels, bicycle rack + + + +ChildItemEntityEntity->childItemCategoryProperty + + +property + + + +childassetIdProperty + + + + + + + +«Property» +childassetId + +preferredName: Child assetId +description: Describes the Catena-X ID of the child part +exampleValue: urn:uuid:218b26f4-4a0b-4a7f-b2c1-d248927718bf + + + +ChildItemEntityEntity->childassetIdProperty + + +property + + + +itemProperty + + + + + + + +«Property» +item + +preferredName: Item +description: The description of the part in the primary language of the +   production facility of the product owner. + + + +ChildItemEntityEntity->itemProperty + + +property + + + +TextCharacteristic + + + + + + + +«Characteristic» +samm-c:Text + +preferredName: Text +description: Describes a Property which contains plain text. This is +   intended exclusively for human readable strings, not for +   identifiers, measurement values, etc. +dataType: string + + + +childItemCategoryProperty->TextCharacteristic + + +characteristic + + + +childassetIdProperty->TextCharacteristic + + +characteristic + + + +ItemCharacteristicCharacteristic + + + + + + + +«Characteristic + Collection» +ItemCharacteristic + +preferredName: Item Characteristic +description: Characteristic of the item. +ordered: false +allowDuplicates: false + + + +itemProperty->ItemCharacteristicCharacteristic + + +characteristic + + + +ItemEntityEntity + + + + + + + +«Entity» +ItemEntity + +preferredName: Item Entity +description: Entity encapsulating the properies describing a item + + + +ItemCharacteristicCharacteristic->ItemEntityEntity + + +dataType + + + +itemDescriptionProperty + + + + + + + +«Property» +itemDescription + +preferredName: Item Description +description: The description of the item in the primary language of the +   production facility of the product owner. +exampleValue: The steering wheel is nice and round + + + +ItemEntityEntity->itemDescriptionProperty + + +property (optional) + + + +itemClassificationProperty + + + + + + + +«Property» +itemClassification + +preferredName: Item Classification +description: The item classification. + + + +ItemEntityEntity->itemClassificationProperty + + +property (optional) + + + +ownerItemIdProperty + + + + + + + +«Property» +ownerItemId + +preferredName: Owner Item ID +description: This is the key field of the component which usually keeps +   the part numbers used in after-sales, e.g. when repairing +   broken parts and searching for a replacement. This +   ownerPartId itself isn't usually bound to one part version, +   with the assumption that all part versions with the same +   ownerPartId are mutually interchangeable. +exampleValue: urn:uuid:b4741433-92bb-4027-9a02-bbc64a58d193 + + + +ItemEntityEntity->ownerItemIdProperty + + +property + + + +itemQuantityProperty + + + + + + + +«Property» +itemQuantity + +preferredName: Item Quantity +description: This is the quantity how often this item is in the item. + + + +ItemEntityEntity->itemQuantityProperty + + +property (optional) + + + +lastModifiedOnProperty + + + + + + + +«Property» +lastModifiedOn + +preferredName: Last Modified On +description: The time the item was modified the last time +exampleValue: 2022-02-03T14:48:54.709Z + + + +ItemEntityEntity->lastModifiedOnProperty + + +property (optional) + + + +createdOnProperty + + + + + + + +«Property» +createdOn + +preferredName: Created On +description: The time the item was created on +exampleValue: 2022-02-03T14:48:54.709Z + + + +ItemEntityEntity->createdOnProperty + + +property (optional) + + + +itemVersionProperty + + + + + + + +«Property» +itemVersion + +preferredName: Item Version +description: This is the version of the item. The engineering will at +   times supercede an older item version by a newer one, which +   might have different material aspects, physical dimensions +   etc., still maintaining compatibility. +exampleValue: 05 + + + +ItemEntityEntity->itemVersionProperty + + +property (optional) + + + +itemPositioningProperty + + + + + + + +«Property» +itemPositioning + +preferredName: Item Positioning +description: Some parts are intended to be used on either the left or +   right side, e.g. mirrors, hence this entity describes on +   which side a part is to be used +exampleValue: left + + + +ItemEntityEntity->itemPositioningProperty + + +property (optional) + + + +itemDescriptionProperty->TextCharacteristic + + +characteristic + + + +ItemClassificationCharacteristicCharacteristic + + + + + + + +«Characteristic + Collection» +ItemClassificationCharacteristic + +preferredName: Item Classification Characteristic +description: The characteristic of the item classification. +ordered: false +allowDuplicates: false + + + +itemClassificationProperty->ItemClassificationCharacteristicCharacteristic + + +characteristic + + + +ItemClassificationEntityEntity + + + + + + + +«Entity» +ItemClassificationEntity + +preferredName: Item Classification Entity +description: The entity encapsulating the properties of the item +   classification. + + + +ItemClassificationCharacteristicCharacteristic->ItemClassificationEntityEntity + + +dataType + + + +keyProperty + + + + + + + +«Property» +key + +preferredName: Key +description: Key within the classification. +exampleValue: BMW:PartFamily + + + +ItemClassificationEntityEntity->keyProperty + + +property + + + +valueProperty + + + + + + + +«Property» +value + +preferredName: Value +description: Value within the classification. +exampleValue: STEEWHL + + + +ItemClassificationEntityEntity->valueProperty + + +property + + + +keyProperty->TextCharacteristic + + +characteristic + + + +valueProperty->TextCharacteristic + + +characteristic + + + +assetIdTraitCharacteristic + + + + + + + +assetIdTraitCharacteristic + + + +ownerItemIdProperty->assetIdTraitCharacteristic + + +characteristic + + + +Uuidv4RegularExpressionConstraint + + + + + + + +Uuidv4RegularExpressionConstraint + + + +assetIdTraitCharacteristic->Uuidv4RegularExpressionConstraint + + +constraint + + + +ItemQuantityCharacteristicCharacteristic + + + + + + + +«Characteristic» +ItemQuantityCharacteristic + +preferredName: Item Quantity Characteristic +description: The characteristic of the item quantity. + + + +itemQuantityProperty->ItemQuantityCharacteristicCharacteristic + + +characteristic + + + +ItemQuantityEntityEntity + + + + + + + +«Entity» +ItemQuantityEntity + +preferredName: Item Quantity Entity +description: The entity encapsulating the properties describing the +   quantity of a item. + + + +ItemQuantityCharacteristicCharacteristic->ItemQuantityEntityEntity + + +dataType + + + +quantityNumberProperty + + + + + + + +«Property» +quantityNumber + +preferredName: Quantity Number +description: The number of objects related to the measurement unit. +exampleValue: 350 + + + +ItemQuantityEntityEntity->quantityNumberProperty + + +property + + + +measurementUnitProperty + + + + + + + +«Property» +measurementUnit + +preferredName: Measurement Unit +description: Unit of measurement for the quantity of serialized objects. +exampleValue: unit:kW + + + +ItemQuantityEntityEntity->measurementUnitProperty + + +property + + + +NumberOfObjectsCharacteristic + + + + + + + +«Characteristic» +NumberOfObjects + +preferredName: Number of Objects +description: Quantifiable number of objects in reference to the +   measurementUnit. +dataType: double + + + +quantityNumberProperty->NumberOfObjectsCharacteristic + + +characteristic + + + +UnitReferenceCharacteristic + + + + + + + +«Characteristic» +samm-c:UnitReference + +preferredName: Unit Reference +description: Describes a Property containing a reference to one of the +   units in the Unit Catalog. +dataType: curie + + + +measurementUnitProperty->UnitReferenceCharacteristic + + +characteristic + + + +curieDatatype + + + + + + + +curieDatatype + + + +UnitReferenceCharacteristic->curieDatatype + + +dataType + + + +TimestampCharacteristic + + + + + + + +«Characteristic» +samm-c:Timestamp + +preferredName: Timestamp +description: Describes a Property which contains the date and time with +   an optional timezone. +dataType: dateTime + + + +lastModifiedOnProperty->TimestampCharacteristic + + +characteristic + + + +createdOnProperty->TimestampCharacteristic + + +characteristic + + + +itemVersionProperty->TextCharacteristic + + +characteristic + + + +ItemPositioningCharacteristicCharacteristic + + + + + + + +«Characteristic + Enumeration» +ItemPositioningCharacteristic + +preferredName: Item Positioning Characteristic +description: Describes the characteristic of the left or right mark +   entity with its possible values (left or right) +dataType: xsd:string +values: left, right + + + +itemPositioningProperty->ItemPositioningCharacteristicCharacteristic + + +characteristic + + + +childItemsProperty + + + + + + + +«Property» +childItems + +preferredName: Child Items +description: The child Items of the observed parent item + + + +childItemsProperty->ChildItemCharacteristicCharacteristic + + +characteristic + + + +manufacturerIdProperty + + + + + + + +«Property» +manufacturerId + +preferredName: Manufacturer ID +description: The ID of the initial issuer of the single level +   BoMAsSpecified +exampleValue: BPNL1234567890LR + + + +manufacturerIdProperty->TextCharacteristic + + +characteristic + + + +assetIdProperty + + + + + + + +«Property» +assetId + +preferredName: assetID +description: A unique reference to an asset which could be registered +   within Catena-X DataSpace +exampleValue: urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d + + + +assetIdProperty->assetIdTraitCharacteristic + + +characteristic + + + +SingleLevelBomAsSpecifiedAspect + + + + + + + +«Aspect» +SingleLevelBomAsSpecified + +preferredName: Single Level BOM as Specified +description: The SingleLevelBomAsSpecified defines the view of the OEM or +   producer of the whole product, e.g. the OEM of a vehicle. It +   is free of any supplier-related information and specifies +   the promised and guaranteed content of the whole product to +   the end customer. This "top-down" view is in contrast to the +   "bottom-up" view of the SingleLevelBoMAsPlanned, though +   several sub-aspects are shared. The BomAsSpecified is merely +   one aspect, which is attached to the twin of the whole +   product and itself does neither introduce further twins nor +   reference them. Instead it merely comprises all functional +   information required by dismantlers, workshops or requestors +   for used parts to search for and to make a match on the +   market place. + + + +SingleLevelBomAsSpecifiedAspect->childItemsProperty + + +property + + + +SingleLevelBomAsSpecifiedAspect->manufacturerIdProperty + + +property + + + +SingleLevelBomAsSpecifiedAspect->assetIdProperty + + +property + + + +timestampProperty + + + + + + + +timestampProperty + + + +timestampProperty->TimestampCharacteristic + + +characteristic + + + diff --git a/versioned_docs/version-24.03/standards/CX-0031-DataModelMaterialForHomologation/CX-0031-DataModelMaterialForHomologation-v1.1.1.md b/docs/standards/CX-0031-DataModelMaterialForHomologation/CX-0031-DataModelMaterialForHomologation.md similarity index 99% rename from versioned_docs/version-24.03/standards/CX-0031-DataModelMaterialForHomologation/CX-0031-DataModelMaterialForHomologation-v1.1.1.md rename to docs/standards/CX-0031-DataModelMaterialForHomologation/CX-0031-DataModelMaterialForHomologation.md index b324ffa13..42f552ec4 100644 --- a/versioned_docs/version-24.03/standards/CX-0031-DataModelMaterialForHomologation/CX-0031-DataModelMaterialForHomologation-v1.1.1.md +++ b/docs/standards/CX-0031-DataModelMaterialForHomologation/CX-0031-DataModelMaterialForHomologation.md @@ -298,3 +298,7 @@ an update will be provided. ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0031-DataModelMaterialForHomologation/assets/MaterialforHomologation.png b/docs/standards/CX-0031-DataModelMaterialForHomologation/assets/MaterialforHomologation.png new file mode 100644 index 000000000..98f96e0fa Binary files /dev/null and b/docs/standards/CX-0031-DataModelMaterialForHomologation/assets/MaterialforHomologation.png differ diff --git a/docs/standards/CX-0032-DataModelPartAsSpecified/CX-0032-DataModelPartAsSpecified.md b/docs/standards/CX-0032-DataModelPartAsSpecified/CX-0032-DataModelPartAsSpecified.md new file mode 100644 index 000000000..f1c99844d --- /dev/null +++ b/docs/standards/CX-0032-DataModelPartAsSpecified/CX-0032-DataModelPartAsSpecified.md @@ -0,0 +1,209 @@ + +# CX-0032 Data Model: Part As Specified v1.0.1 + +## ABSTRACT + +A core problem of the circular economy is making the right decisions. These strategies include Rethink, Refuse, Reduce, Reuse, Refurbish, Redesign, Recycle, Recover and Rot. +In particular, the end of life (EoL) decisions are a challenge. In order for a circular economy to scale, however, these must be supported in a standardized way. The present data model is used for this purpose. This supports the products R-Strategy Assistant & Circularity Dashboard to provide decision support for its users. In this first scope, the model should support the EoL decisions in particular. +The data provided by the data provider allows relevant decisions to be derived. This leads to higher reuse and recycling rates, an economically and ecologically balanced decision-making process and a scaled circular economy. + +## 1.INTRODUCTION + +The aspect model PartAsSpecified belongs to the part catalogue. A PartAsSpecified represents a certain OEM catalog part on part number level, providing a digital representation of the part as specified by the OEM. The link to the serialized part is done via the partId, this can only be done if the respective digital twins were provided by the supplier within the value chain. + +### 1.1 PURPOSE OF THE DOCUMENT + +The purpose of this document is the description of the Asset Administration Shell submodel bill of material (BoM) as specified. It defines the view of the producing company of the produced product. The presented data model is described and illustrated in the following with the entities and properties and their interrelationships. + +### 1.2 SCOPE OF THE IMPLEMENTATION + +> *This section is non-normative* + +This chapter serves to situate the given reference implementation, to outline its prerequisites and to point out its limitations. + +### 1.3 PRECONDITIONS AND DEPENDENCIES + +> *This section is non-normative* + +Like all Catena-X data models, this model will be available in a machine-readable format on GitHub. This aspect model is written in BAMM 2.0 as a modeling language, which is a separate industry standard from the open manufacturing platform, see Open Manufacturing. The data contained in this Catena-X data model is requested and exchanged via Catena-X using an Eclipse Dataspace Connector (EDC), which is a separate Catena-X standard and an implementation of the IDSA standard. + +### 1.4 CONSTRAINTS AND LIMITATIONS + +> *This section is non-normative* + +There are no constraints and limitations to this reference implementation document. + +### 1.5 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +### 1.6 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will MUST to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +### 1.7 EXAMPLE + +The following json gives an overview of the data model. + +```json +{ + "partTypeInformation": { + "partClassification": [{ + "value": "STEEWHL", + "key": "BMW:PartFamily" + } + ], + "ownerPartId": "94A2032", + "partVersion": "05", + "itemCategory": "component", + "nameAtOwner": "Steering Wheel", + "partDescription": "The steering wheel is nice and round" + }, + "validityPeriod": { + "validFrom": "2023-02-10T07:17:52.396Z", + "validTo": "2023-02-10T07:17:52.396Z" + }, + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379" +} +``` + +### 1.8 TERMINOLOGY + +> *This section is non-normative* + +The following terms are especially relevant for the understanding of the standard: + +Business Partner Number (BPN) +: A BPN is the unique identifier of a partner within Catena-x + +End of life vehicle (EoL vehicle) +: 'End-of life vehicle' means a vehicle which is waste within the meaning of Article 1(a) of Directive 75/442/EEC on waste (waste means any substance or object which the holder disposes of or is required to dispose of pursuant to the provisions of national law in force). + +Original Equipment Manufacturer (OEM) +:An original equipment manufacturer (OEM) is generally perceived as a company that produces non-aftermarket parts and equipment that may be marketed by another manufacturer. + +Bill of material (BOM) +:A bill of material is a list of the raw materials, sub-assemblies, intermediate assemblies, sub-components, parts, and the quantities of each needed to manufacture an end product. + +Eclipse Dataspace Connector (EDC) +:The Eclipse Dataspace Connector provides a framework for sovereign, inter-organizational data exchange. + +## 2 ASPECT MODEL ""PartAsSpecified"" + +> *This section is normative* + +### 2.1 INTRODUCTION + +The purpose of this document is the description of the Asset Administration Shell submodel PartAsSpecified. The presented data model is described and illustrated in the following with the entities and properties and their interrelationships. + +Every data provider MUST provide the data +conformant to the semantic model specified in this document. + +The unique identifier of the semantic model specified in this document +**MUST** be used by the data provider to define the semantics of the data +being transferred. + +Every certified business application using the PartAsSpecified data **MUST** +be able to consume data conformant to the semantic model specified in +this document. + +This semantic model **MUST** be made available in the central Semantic Hub. + +Data consumers and data provider **MUST** comply with the license of the +semantic model. + +In the Catena-X data space PartAsSpecified data MUST be requested and +exchanged via Eclipse Dataspace Connector (EDC) conformant to [CX-0018](#3-references) +and [CX-0002](#31-normative-references). + +The JSON Payload of data providers MUST be conformant to the JSON Schema +as specified in this document. + +### 2.2 SPECIFICATION ARTIFACTS + +The modelling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#32-non-normative-references). + +This aspect model is written in BAMM 2.0.0 as a modeling language conformant to [CX-0003](#31-normative-references) as input for the semantic deriven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub2F2F conformant to [CX-0003](#31-normative-references). + +### 2.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group Digital Product Pass (DPP).This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons4F4F. + +### 2.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier: + +```txt +urn:bamm:io.catenax.bom_as_specified:2.0.0#PartAsSpecified +``` + +### 2.5 FORMATS OF SEMANTIC MODEL + +All different formats of the semantic model can be found in the github repository. + +```txt +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_as_specified/2.0.0 +``` + +#### 2.5.1 RDF Turtle + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. It can be accessed via github: + +```txt +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.part_as_specified/2.0.0/PartAsSpecified.ttl +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. These other formats are saved in the "gen" folder in github: + +```txt +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_as_specified/2.0.0/gen +``` + +#### 2.5.2 JSON Schema + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". + +```txt +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.part_as_specified/2.0.0/gen/PartAsSpecified-schema.json +``` + +#### 2.5.3 aasx + +A AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification conformant to \[[SMT](#32-non-normative-references)]. + +Note: As soon as the specification V3.0 of the Asset Administration Shell specification is available +and update will be provided. + +### 2.6 SEMANTIC MODEL + +The data model is described in BAMM 2.0.0. A html documentation can be generated from the rdf turtle file. + +## 3. References + +### 3.1 NORMATIVE REFERENCES + +- [CX-0003 BAMM Aspect Meta Model v1.0.2](https://catena-x.net/de/standard-library) +- [CX-0002 Digital Twins in Catena - X v2.0.0](https://catena-x.net/de/standard-library) +- [CX-0018 Sovereign Data Exchange (EDC) v2.0.1](https://catena-x.net/de/standard-library) + +### 3.2 NON-NORMATIVE REFERENCES + +- [SMT- How to create submodel template specification](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf) + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +![PartAsSpecified](./assets/image.png) + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0032-DataModelPartAsSpecified/assets/image.png b/docs/standards/CX-0032-DataModelPartAsSpecified/assets/image.png new file mode 100644 index 000000000..ebb564d69 Binary files /dev/null and b/docs/standards/CX-0032-DataModelPartAsSpecified/assets/image.png differ diff --git a/docs/standards/CX-0044-ECLASS/CX-0044-ECLASS.md b/docs/standards/CX-0044-ECLASS/CX-0044-ECLASS.md new file mode 100644 index 000000000..c6c179a5f --- /dev/null +++ b/docs/standards/CX-0044-ECLASS/CX-0044-ECLASS.md @@ -0,0 +1,276 @@ +# CX-0044 ECLASS v1.0.2 + +## ABSTRACT + +ECLASS[^3] is an international cross-industry master-data business +standard for products and services information to be exchanged. The +ECLASS data dictionary is based on ISO and IEC standards and is an +important enabler for interoperability. ECLASS is since 2000 in the +market and widespread used in many industries. Therefore, ECLASS has a +state-of-the-art infrastructure and experience to further develop and +maintain a semantic dictionary. + +The Asset Administration Shell (AAS) has standardized the structure +including the different submodels defined in IDTA, and ECLASS has +standardized the semantics for information elements used for the +definition of digital twins. + +ECLASS is the recommended dictionary by Plattform Industrie 4.0 for the +creation of Asset Administration Shell and Digital Twins. Therefore, +ECLASS is to be preferred within Catena-X for the semantic description +of models and their attributes. Thus, if the semantic description of an +asset or its properties is available in the ECLASS dictionary, then it +shall be used. If it is not part of ECLASS, alternatives can be used. In +parallel, a change request should be made to ECLASS to add the necessary +information in the next release so that it is available for Catena-X in +the future. + +## 1. Introduction + +### 1.1 Audience & Scope + +> *This section is non-normative* + +The standard is relevant for: + +- Data Provider / Consumer +- Enablement Service Provider +- Consulting Services Provider + +The standard is relevant for the description of assets and their +properties. + +### 1.2 Context + +ECLASS[^4] is a cross-industry master-data business standard for +products and services information to be exchanged in a computer-sensible +form across all borders -- across sectors, countries, languages, and +organizations. The ECLASS data dictionary is based on ISO 13584-42 and +IEC 61360-2. It is used, for instance, for the exchange of product data +for procurement, eCommerce, and engineering tools. + +ECLASS is a formal semantic dictionary that is used for product +description and product classification. The information model used by +ECLASS is the foundation for the classification and description of +products and services. It allows the reuse of generic descriptions in +multiple business domains, the mapping to other dictionaries, and +ensures the upgradability of the ECLASS dictionary. + +ECLASS is recommended by Plattform Industrie 4.0 for the creation of +Asset Administration Shell and Digital Twins[^2]. + +The Asset Administration Shell (AAS) has standardized the structure +(including the different submodels defined in IDTA), and ECLASS has +standardized the semantics for information elements used for the +definition of digital twins. + +ECLASS is seen as a key element of an AAS and integral for semantic +interoperability in its submodels. The document[^5] "Modelling the +Semantics of Data of an Asset Administration Shell with Elements of +ECLASS" provides modeling details. + +### 1.3 ECLASS Overview + +The data model of ECLASS is shortly depicted in ECLASS website[^1]. +ECLASS is a formal semantic dictionary which is used for product +description and product classification. The ECLASS dictionary is +maintained in Releases. Each Release is containing an exhaustively +defined and reproduceable set of structure elements. + +ECLASS uses globally unique identifiers for every Structure Element +included in the ECLASS Standard. This globally unique identifier is +called IRDI (International Registration Data Identifier). These +identifiers are used to ensure that the semantic of an element is unique +in the overall system. The IRDI is based on the international standards +ISO/IEC 11179-6, ISO 29002, and ISO 6532. Every institution registered +by the registration authority has a unique ICD (International Code +Designator) identifier. In the case of ECLASS this is the "0173". ECLASS +Dictionary provides IRDIs for all Structure Elements e.g., +Classification Classes, Application Classes, Properties, Units of +Measure, Property Values (in case of coded values), Value Lists, +Aspects, Blocks and Templates. For example, the IRDI +0173-1#02-AAO677#002 stands for a property defining the "Manufacturer +name". + +ECLASS is an open standard based on global IEC standards. The +development is openly designed, content can be contributed by anyone, +the data model is open and licensed free of charge for the recipients of +the data. An ECLASS license is needed to describe commercial products. +Additional details can be obtained from the ECLASS website[^6]. For +testing and development of Catena-X models there is no cost. In +addition, ECLASS recently released Release 13 with the Asset XML +containing IDTA submodels, which are also free of charge also for +productive use. + +Details on the model can be acquired from the ECLASS conceptual data +model specs[^7]. + +### 1.4 Conformance + +As well as sections marked as non-normative, all authoring guidelines, +diagrams, examples, and notes in this specification are non-normative. +Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, +SHOULD and SHOULD NOT in this document are to be interpreted as +described in [BCP +14](https://datatracker.ietf.org/doc/html/bcp14) \[[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)\] +\[[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)\] when, and +only when, they appear in all capitals, as shown here. + +### 1.5 Proof of Conformity + +> *This section is non-normative* + +ECLASS is relevant to all semantic models developed in Catena-X which in +future releases should utilize ECLASS for semantic interoperability. +Future releases may include all model reference implementations and +relative processes. + +All participants and their solutions will need to prove that they +conform to the Catena-X standards. To validate that the standards are +applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +The concept description of an AAS Element can be defined with elements +of ECLASS. In general, the principle followed is to make semantics +explicitly by using standardized ECLASS Elements. + +To prove conformity, the resulting semantic models developed SHOULD + +- utilize ECLASS for the semantic description of assets by using the respective IRDIs. + +- explicitly state the absence of the specific attributes in ECLASS as justification of not using it. + +### 1.6 Examples + +ECLASS has released a document^2^ describing how AAS and ECLASS can be +utilized. More specific documents for the use of ECLASS within the AAS +are on the way. All of it will be available on the ECLASS and IDTA +website. + +The essential functional elements of the AAS are submodels, which +comprise descriptive properties, configuration parameters, variables, +files, offered capabilities and operations of the asset in a +machine-interpretable form. Submodels are information models that +describe a specific aspect of an asset. Each submodel and all its +elements have a semantic ID. This semantic ID is inherited by submodels, +submodel elements, qualifiers and views and is a reference to a unique +identifier. Extensions and external asset IDs also exist. These elements +do also have a semantic ID. + +The ECLASS standard should be used for this semantic ID. The concept +description of an AAS Element can be defined with elements of ECLASS. In +general, the principle followed is to make semantics explicitly by using +standardized ECLASS Elements. + +![Mapping of a Property with different Categories to an ECLASS +Property](./assets/CX-0044_Picture.jpg) + +Figure: Mapping of a Property with different Categories to an ECLASS +Property[^2] + +ECLASS, with its Release 13.0 in 2022, contains enhancements for the +Asset Administration Shell (AAS). Regarding the data model, a new +application class of type "Asset" has been introduced in addition to +BASIC and ADVANCED. Furthermore, features can have the data types +\"File\" and \"Blob\". In addition, AAS submodel templates were adhering +to the IDTA standardized submodels "Handover Documentation" and "Digital +Nameplate for Industrial Equipment". + +Further technical details can be found in the respective webpage[^8]. + +### 1.7 TERMINOLOGY + +> *This section is non-normative* + +**AAS** +Asset Administration Shell + +**IRDI** + +International Registration Data Identifier + +**IDTA** + +Industrial Digital Twin Association e.V. + +Additional terminology used in this standard can be looked up in the +glossary on the association homepage. + +## 2. Usage of ECLASS Semantics in Catena-X + +> *This section is normative* + +The usage of ECLASS in Catena-X standardized semantic models is an +important enabler for interoperability. If any model is to be +standardized in Catena-X according to "CX-0003 Semantic Aspect meta +model (SAMM)", then it SHOULD be checked if ECLASS can cover parts of +the model with appropriate semantic descriptions. + +![Process of semantic description with ECLASS](./assets/CX-0044_Picture_2.jpg) + +Figure: Process of semantic description with ECLASS + +Specifically, as shown in Figure 1, the following investigative steps +SHOULD be carried out: + +- If the semantic description of an asset or its properties exists in the ECLASS dictionary, then it SHOULD be used to describe it. +- In case the ECLASS dictionary does not have the necessary information then: + - Alternatives MAY be used, e.g., own, or alternative dictionary. + - In parallel a request SHOULD be made to ECLASS to add the necessary information in its next release so that this can be used in the future. + +ECLASS is an open standard which is constantly further being developed +to respond to changes in the market. As such, anyone independent whether +they are ECLASS members or not, can submit change requests in order to +introduce or revise ECLASS content. Hence, as shown in Figure 1, such a +submission SHOULD be made to ECLASS. Subsequently, when ECLASS +introduces the needed changes in its future release, the Catena-X model +SHOULD use the requested content. Further info on how such requests can +be submitted to ECLASS is described in detail on the respective ECLASS +webpage[^9]. + +## 3. References + +### 3.1 Normative References + +The ECLASS[^10] website provides concrete info and tools with respect to +understanding and utilizing the ECLASS standard. + +### 3.2 Non-Normative References + +> *This section is non-normative* + +In addition to the ECLASS[^11] website additional documents enable the +better understanding of ECLASS usage in conjunction with Asset +Administration Shell and Digital Twins^2^. The ECLASS Release 13.0 +contains enhancements for the Asset Administration Shell (AAS) that +include a new application class of type "Asset". Technical details can +be found on the respective webpage[^12]. + +[^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf + +[^2]: https://catena-x.net/de/standard-librar + +[^3]: https://eclass.eu + +[^4]: https://eclass.eu + +[^5]: https://eclass.eu/fileadmin/Redaktion/pdf-Dateien/Broschueren/2021-06-29_Whitepaper_PlattformI40-ECLASS.pdf + +[^6]: https://eclass.eu/en/eclass-standard/licenses + +[^7]: https://eclass.eu/support/technical-specification/data-model/conceptual-data-model + +[^8]: https://eclass.eu/shop/en/product/eclass-13-0-asset + +[^9]: https://eclass.eu/support/guides/change-request + +[^10]: https://eclass.eu + +[^11]: https://eclass.eu + +[^12]: https://eclass.eu/shop/en/product/eclass-13-0-asset + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0044-ECLASS/assets/CX-0044_Picture.jpg b/docs/standards/CX-0044-ECLASS/assets/CX-0044_Picture.jpg new file mode 100644 index 000000000..6cf5f83ee Binary files /dev/null and b/docs/standards/CX-0044-ECLASS/assets/CX-0044_Picture.jpg differ diff --git a/docs/standards/CX-0044-ECLASS/assets/CX-0044_Picture_2.jpg b/docs/standards/CX-0044-ECLASS/assets/CX-0044_Picture_2.jpg new file mode 100644 index 000000000..dd968f89a Binary files /dev/null and b/docs/standards/CX-0044-ECLASS/assets/CX-0044_Picture_2.jpg differ diff --git a/docs/standards/CX-0045-AspectModelDataChainTemplate/CX-0045-AspectModelDataChainTemplate.md b/docs/standards/CX-0045-AspectModelDataChainTemplate/CX-0045-AspectModelDataChainTemplate.md new file mode 100644 index 000000000..e763d5ea9 --- /dev/null +++ b/docs/standards/CX-0045-AspectModelDataChainTemplate/CX-0045-AspectModelDataChainTemplate.md @@ -0,0 +1,316 @@ +# CX-0045 Aspect Model Data Chain Template v1.3.0 + +## ABSTRACT + +This component of the capability Cross Company Data Chain Management is a data model, so that the +Item Relationship Service API, and other applications can work not only on existing semantic models, +but also, to new defined data chain relevant aspect models which fit to the template. +With this model template in place, interoperability is being provided, because participants defining +their connection between digital twins according to that template, will be able to access connected data. +A data chain is a chain of linked data. The minimal set of information necessary to build this are +two objects and one link between those objects. Objects in Catena-X are called Asset Administration +Shell (AAS) or digital twins and linked digital twins are data chains. This template describes the +minimal information of a link between two digital twins, so the most flexibility is given for +further use-cases to build use-case specific data chains. + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +> *Relevant only for existing standards. At the new standard, please delete* + +## 1 INTRODUCTION + +This component is used to standardize the way in which an aspect model of a digital twin needs to be +modelled, so that services and products which consume linked data can work and that an +interoperability on data chain level can exist. It is a minimal set of conditions to be applied to +such aspect models that model a connection between two digital twins. +This minimal set of conditions shall guide developer of new services and semantic models in the +process of creating new solutions for Catena-X. It is an easy extendable template to fit the +use-case needs. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +List for which roles the standard is relevant. + +- Core Service Provider +- Data Provider +- Business Application Provider +- Enablement Service Provider +- Consulting Provider + +This standard is only applicable when a use-case has the need to extend existing Aspect Models +with models connecting several Digital Twins. When a use-case has the need to extend the +existing Aspect Models with models which connect several Digital Twins with each other. Then this +standard applies. +A so-called Data Chain exists when multiple Digital Twins are semantically connected to each other. +For example, a Bill of Materials (BoM) Structure, where each part results in a separate Digital Twin. +To have the same structure on how Data Chains can be built this template applies. This provides a +lean structure that can be extended with Use-Case specific information and attributes. + +This standard is only to be applied in the creation process of new aspect models, which connects +digital twins in the Catena-X Network. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +The following dependencies and preconditions exist. This aspect model template is written in +SAMM 2.0 as a modeling language, which is an industry standard from the [Eclipse Semantic Modelling Framework]( https://eclipse-esmf.github.io/esmf-documentation/index.html). + +SAMM is used to model Asset Administration Shell submodels, which are attached to digital twins in +the form of an Asset Administration Shell (AAS). All submodels in Catena-X are managed in the +semantic hub https://github.com/eclipse-tractusx/sldt-semantic-hub. A data model is requested and exchanged via Catena-X using an Eclipse Dataspace +Connector (see chapter 3.1 NORMATIVE REFERENCES), which is a separate Catena-X standard. An EDC is discovered by the EDC Discovery Flow (see chapter 3.1 NORMATIVE REFERENCES). + +The following preconditions must be met that a developer is bound to use this template as reference: + +- The to be developed semantic model describes a data chain (e.g., linking one digital twin with another) +- The to be developed semantic model is used or meant to be accessed by multiple use-cases. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to prove, that they are conform +with the Catena-X standards. To validate that the standards are applied +correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To prove conformity with the Data Chain Template, use the schema (see Chapter 2.1.1 JSON Schema) and check if the +necessary structure is implicitly in the Aspect to prove. What is necessary: + +- The Object structure **MUST** match the template, but **MAY** contain more attributes +- see chapter [2 DATA CHAIN ASPECT TEMPLATE](#2-data-chain-aspect-template) for more conformity assessment criteria + +### 1.4 EXAMPLES + +The JSON schema describes the schema of the template. The following examples show +minimal setups of this template. + +```json +{ + "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d", + "childItems": [ + { + "catenaXId": "urn:uuid:7BeA9fAE-A1ca-D164-3BDF-0E5bac5E5b7d", + "businessPartner" : "BPNL50096894aXYZ" + } + ] +} +``` + +or + +```json +{ + "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d", + "parentItems": [ + { + "catenaXId": "urn:uuid:7BeA9fAE-A1ca-D164-3BDF-0E5bac5E5b7d", + "businessPartner" : "BPNL50096894aXYZ" + } + ] +} +``` + +This template describes the minimal necessary set of attributes for a valid data chain in Catena-X. +A digital twin with a catenaXId and at least one linked “child” catenaXId or "parent" catenaXId is necessary to connect two individual digital +twins, which can be provided by different companies. The use-cases have the possibility to +extend this to their behalf and publish it as a separate Aspect Model. + +The partentItems and the childItems contain objects with at least a catenaXId to identify the digital twin and a businessPartner to identify where to find the digital twin. + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +Aspect Meta Model (SAMM): A Meta description model to describe AAS + +Business Partner Number (BPN): A BPN is the unique identifier of a partner within Catena-x. + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 DATA CHAIN ASPECT TEMPLATE + +> *This section is normative* + +The purpose of this data model is to enable newly defined data chain relevant aspect models to +operate with the Item Relationship Service API, which is described in a separate [reference implementation](https://github.com/eclipse-tractusx/item-relationship-service). + +Classical naming convention: + +- the object **MUST** be a digital twin / AAS (Asset Administration Shell) +- the object **MUST** be identified by catenaXId +- the array of “child” objects **MUST** be identified by childItems +- the array of “child” objects **MUST** contain at least one element +- the item of a child item array element **MUST** be identified by catenaXId and a businessPartner (BPN) +- the array of "parent" objects **MUST** be identified by parentItems +- the array of "parent" objects **MUST** contain at least one element +- the item of a parent item array element **MUST** be identified by catenaXId and a businessPartner (BPN) +- the parameter businessPartner **MUST** be a BPNL + +This template **MAY** be extended with use-case specific attributes. The template **MUST** be +published as a new aspect model. + +Changes in the minimal aspect model regarding the relationship of a data chain **RECOMMENDED** to be +always backward compatible, so that existing data chains do not break. + +### 2.1 FORMATS OF TEMPLATE + +#### 2.1.1 JSON Schema + +##### 2.1.1.1 JSON schema for relationship types of children + +```json +{ + "$schema": "https://json-schema.org/draft-04/schema", + "type": "object", + "components": { + "schemas": { + "urn_samm_io.catenax.relationship_template_0.0.0_CatenaXIdTraitCharacteristic": { + "type": "string", + "pattern": "(^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)|(^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)" + }, + "urn_samm_io.catenax.relationship_template_0.0.0_BpnTrait": { + "type" : "string", + "pattern" : "^(BPNL)([0-9]{8})([a-zA-Z0-9]{4})$" + }, + "urn_samm_io.catenax.relationship_template_0.0.0_ChildData": { + "type": "object", + "properties": { + "catenaXId": { + "$ref": "#/components/schemas/urn_samm_io.catenax.relationship_template_0.0.0_CatenaXIdTraitCharacteristic" + }, + "businessPartner": { + "$ref": "#/components/schemas/urn_samm_io.catenax.relationship_template_0.0.0_BpnTrait" + } + }, + "required": [ + "catenaXId", + "businessPartner" + ] + }, + "urn_samm_io.catenax.relationship_template_0.0.0_SetOfChildPartsCharacteristic": { + "type": "array", + "items": { + "$ref": "#/components/schemas/urn_samm_io.catenax.relationship_template_0.0.0_ChildData" + }, + "uniqueItems": true + } + } + }, + "properties": { + "catenaXId": { + "$ref": "#/components/schemas/urn_samm_io.catenax.relationship_template_0.0.0_CatenaXIdTraitCharacteristic" + }, + "childItems": { + "$ref": "#/components/schemas/urn_samm_io.catenax.relationship_template_0.0.0_SetOfChildPartsCharacteristic" + } + }, + "required": [ + "catenaXId", + "childItems" + ] +} +``` + +##### 2.1.1.2 JSON Schema for Relationship types of parent + +```json +{ + "$schema": "https://json-schema.org/draft-04/schema", + "type": "object", + "components": { + "schemas": { + "urn_samm_io.catenax.relationship_template_0.0.0_CatenaXIdTraitCharacteristic": { + "type": "string", + "pattern": "(^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)|(^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)" + }, + "urn_samm_io.catenax.relationship_template_0.0.0_BpnTrait": { + "type" : "string", + "pattern" : "^(BPNL)([0-9]{8})([a-zA-Z0-9]{4})$" + }, + "urn_samm_io.catenax.relationship_template_0.0.0_ParentData": { + "type": "object", + "properties": { + "catenaXId": { + "$ref": "#/components/schemas/urn_samm_io.catenax.relationship_template_0.0.0_CatenaXIdTraitCharacteristic" + }, + "businessPartner": { + "$ref": "#/components/schemas/urn_samm_io.catenax.relationship_template_0.0.0_BpnTrait" + } + + }, + "required": [ + "catenaXId", + "businessPartner" + ] + }, + "urn_samm_io.catenax.relationship_template_0.0.0_SetOfParentPartsCharacteristic": { + "type": "array", + "items": { + "$ref": "#/components/schemas/urn_samm_io.catenax.relationship_template_0.0.0_ParentData" + }, + "uniqueItems": true + } + } + }, + "properties": { + "catenaXId": { + "$ref": "#/components/schemas/urn_samm_io.catenax.relationship_template_0.0.0_CatenaXIdTraitCharacteristic" + }, + "parentItems": { + "$ref": "#/components/schemas/urn_samm_io.catenax.relationship_template_0.0.0_SetOfParentPartsCharacteristic" + } + }, + "required": [ + "catenaXId", + "parentItems" + ] +} +``` + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +- “Digital Twins in Catena-X v2.2.0” [CX-0002] +- “SAMM Aspect Meta Model v1.1.0” [CX-0003] +- “Business Partner Number v2.0.0” [CX-0010] + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- “EDC Discovery API v1.0.2” [CX-0001] + +Aspect models built upon this template: + +- “IndustryCorePartType v2.0.0" [CX-0126] +- "IndustryCorePartInstance v2.0.0" [CX-0127] + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +not applicable + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +not applicable + +### TABLES + +> *This section is non-normative* + +not applicable + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic.md b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic.md new file mode 100644 index 000000000..2b76a6bf2 --- /dev/null +++ b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic.md @@ -0,0 +1,622 @@ +# CX-0046 Demand and Capacity Management Process and Core Business Logic v1.0.0 + +## DISCLAIMER REGARDING DEMAND AND CAPACITY MANAGEMENT DATA EXCHANGE + +This document describes and standardizes certain data exchange business processes, data models +and/or APIs in connection with cross-company demand and capacity management (DCM) based on the +Catena-X data ecosystem. Nothing in this document is meant to determine the contractual terms and +conditions for the purchase, supply, delivery or licensing of any products or services among the +participants of the DCM data exchange. These terms and conditions are separately negotiated and +agreed among suppliers and customers in individual purchase, supply or license agreements. +In case of any inconsistencies with the content of this document, the provisions of individual +agreements among the participants shall prevail over the content of this document. + +## ABSTRACT + +Resilience has become an imperative within Supply Chain Management especially over the past years. +Disruptions of global Supply Chains in terms of material availability but also from logistics +perspective during the SARS-CoV-2 crisis showed the need for additional countermeasures and +technologies with regards to resiliency. Inside the volatile and highly complex surrounding of the +automotive industry, several interfaces of individual IT-solutions exist inside and between the +multiple players along the value chain. There is no common understanding of the process established +across all the partners. Demand and Capacity Management (DCM) focuses on the exchange of demand and +capacity data between a customer and a supplier. + +The purpose of this document is to outline a common understanding of relevant processes and data for +a one-to-one business relationship in the context of DCM and prepare a baseline for a more efficient +and proactive collaboration. + +Companies need this common understanding to enable an exchange of the related data across different +business partners and their systems. + +This document is meant to describe the data exchange and a common core business logic to interpret +them, thereby following the same approach for all partners involved in the DCM process. + +The core business logic MUST be implemented in applications participating in the process and +enabling the exchange of data between the partners involved in DCM. + +## 1. INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This document addresses the following actors: + +- Data Provider / Consumer +- Business Application Provider + +For a better understanding of the roles and responsibility of each actor, please refer to chapter +[2.2](#22-actors-and-roles) + +The following regulations are in scope of the standard description: + +All actors (Data Providers, Data Consumer, Business Application Providers) MUST follow Catena-X +standards with regards to: + +| Number | **Standard** | +| --- | --- | +| [CX-0001](#31-normative-references) | EDC Discovery API, Version 1.0.1 (see chapter [2.8](#28-edc-policies)) | +| [CX-0003](#31-normative-references) | SAMM Aspect Meta Model, Version 1.0.1 | +| [CX-0006](#31-normative-references) | Registration and initial onboarding, Version 1.1.1 | +| [CX-0010](#31-normative-references) | Business Partner Number (BPN), Version 1.0.1 | +| [CX-0015](#31-normative-references) | IAM & Access Control Paradigm, Version 1.0.1 | +| [CX-0047](#31-normative-references) | Demand and Capacity Management Data Models, Version 1.0.0 | +| [CX-0048](#31-normative-references) | Demand and Capacity Management APIs, Version 1.0.0 | + +To run the DCM process, customers and suppliers depend on accurate planning capabilities, as well as +the ability to quickly adapt to changes. + +Standardization of data and methods in DCM means that data consumers, data providers or business +application providers MUST adopt a consistent core business logic to enable an interoperable data +exchange. + +This document refers to a direct one-to-one business relationship between two parties (customer & +supplier). Further relationships and collaboration in an extended supply chain and/or a network will +be part of future standardization packages. + +DCM focuses on a tactical future horizon where demand and capacities can be managed (for details +refer to chapter [2.5](#25-provisioning-demand-data-to-supplier)). + +How customers or suppliers calculate their respective demand or capacity data is excluded from this +standardization. Derivation of measures in the respective companies is excluded, too. + +Visuals/pictures as well as actors and their roles are used to exemplify concepts or processes and +are not intended for mandatory use. + +### 1.2 CONTEXT + +> *This section is non-normative* + +DCM is a critical aspect of Supply Chain Management, as it impacts the ability of suppliers to meet +customers' demand while controlling costs. Effective DCM requires a balance between forecasting +demand, optimizing production capacity and managing inventory levels to quickly adapt to changes. + +The core business logic described in this document enables companies to share data in a sovereign +way as well as to utilize a common process understanding, ensuring interoperability and enabling the +involved parties to achieve the following goals: + +- early identification of upcoming potential bottlenecks, as well as surplus capacity +- better monitoring and control of resources and facilities +- collaboration and decision-making between supplier and customer in order to resolve bottleneck or + surplus situations +- enabling automation of processes +- improvement of efficiency and accuracy + +### 1.3 ARCHITECTURE OVERVIEW + +> *This section is non-normative* + +Not applicable. + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, +**SHOULD** and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 +[RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they are conform with the Catena-X +standards. To validate that the standards are applied correctly, Catena-X employs Conformity +Assessment Bodies (CABs). Please refer to: *[!LINK Conformity Assessment]* for the process of +conformity assessment and certification. + +Any actor participating in the Catena-X DCM use case, MUST implement and follow the following +standards: + +- The DCM core business logic – described in this standard +- The DCM standardized API – described in the \[[CX-0048](#31-normative-references)] standard +- The DCM standardized Data Models – described in the \[[CX-0047](#31-normative-references)] + standard + +Please be aware that dependent on the process step, different (sub-) standards may be relevant. For +instance, when exchanging material demands information, only the standard API MaterialDemand as well +as the standardized data model for `WeekBasedMaterialDemand` are relevant. + +In case of exchange of capacity information, the same logic is relevant (I.e. only the standard API +for CapacityGroup as well as the standardized data model for `WeekBasedCapacityGroup` MUST be used). + +### 1.6 EXAMPLES + +Any **application provider** that develops DCM solutions has to grant the fulfillment of these +requirements: + +- The solution has been designed to specify requirements for a trusted usage environment (e.g. + identity verification and /or verification process), +- The solution is designed to require a contractual agreement in compliance with antitrust + requirements in the usage environment (e.g. data contracts as a prerequisite for carrying out a + data exchange). For reference see Chapter [2.8](#28-edc-policies) and follow EDC guidelines in + \[[CX-0018](#31-normative-references)]. Both customer and supplier agreed upfront to share data + related to DCM. +- The solution has been designed to limit visibility and/or access to concrete data content as much + as possible (e.g. data offer does not yet allow data access). +- The solution has been designed to require the implementation of notice and/or acknowledgement + concepts to raise awareness of antitrust issues during use (e.g. helpdesk or pop-up info). +- The solution has been designed to ensure traceability/reconstructability of processes through + appropriate documentation and at the same time data sovereignty over concrete data content (e.g. + through access, deletion or destination rights). + +Any **customer and supplier in the DCM process** (I.e. data provider and/or data consumer) MUST +fulfil following requirements: + +- Each application enabling and/or participating in the exchange of data as part of the damand and + capacity management process MUST implement the core business logic defined in [Chapter 2](#2-main-content). +- Standardization of data and methods in DCM means that data consumers, data providers or business + application providers MUST adopt a consistent core business logic as defined in [Chapter 2](#2-main-content) + to enable an interoperable data exchange. +- Customer and supplier are in a contractual relationship with each other and agree to share data + related to DCM +- Access authorization to a DCM solution and to its related data will be self-managed by the customer + and supplier companies themselves. +- Customer and supplier MUST be technically able to apply these EDC policies in order to enable a + secure collaborative data exchange +- Customer and supplier MUST follow the antitrust requirements +- Customer and supplier MUST agree on a common unit of measure (see [Table 1](#tables) in + [ANNEXES](#annexes)) defined at product level to be used for data exchange purposes (e.g. demand & + capacities) +- Both parties are technically able to participate within the DCM process. +- The supplier MUST be able to receive the material demand from the customer. +- The customer owns and MUST publish its own demand with its supplier for the future horizon and it + is highly RECOMMENDED to avoid any gaps as far as possible and to share demand data at least till + month 9, to ensure DCM participants to have also sufficient demand data to work with. +- Demand quantities refer to a period of one calendar week (weekly buckets) +- Demands MUST be considered that are not yet fixed, but related to "opportunities" (e.g. projects) + that will realistically materialize as single-orders +- Demand data & quantities MUST refer to one of the categories defined in the table in chapter + [2.5.1](#251-detailed-description-of-demand) of this document +- Demand MUST be consistent with other exchanged data, e.g. call-offs/scheduling agreements +- Material demands data MUST be updated and provided to supplier, whenever changes apply +- The supplier owns and MUST publish capacity data to the customer, referring to material demand + data shared +- Capacity information MUST be used as follows: + - the **"actual capacity"** is the planned available capacity of a supplier + - and the **"maximum capacity**" is the maximum releasable capacity of a supplier (it MAY be equal + or MAY be larger than the "actual capacity" but MUST NOT be smaller than actual capacity) + - When the maximum capacity is larger than the "actual capacity", the difference is called + **"flexible capacity".** +- The customer MUST be able to receive the capacity group incl. the capacity information. +- The supplier that uses the capacity group MUST link at least one material demand information to + it, however often several material demand information are linked. This builds up the foundation to + reflect the corresponding capacity situation of the supplier. +- The aspect model `WeekBasedCapacityGroup` MUST be used by a supplier to provide capacity + information to the customer. +- Based on the aspect model `WeekBasedCapacityGroup` and `WeekBasedMaterialDemand`, both supplier and + customer MUST apply the matching logic defined in [Chapter 2.7](#27-comparison-of-demand-and-capacity-data-within-a-capacity-group) + to ensure a common interpretation of the data. +- Business application provider, data provider or data consumer MUST enable their DCM system to + recognize the matching situation based on the table below and MUST be able to interpret the + matching result accordingly. + +### 1.7 TERMINOLOGY + +> *This section is non-normative* + +| **Term** | **Description** | +| --- | --- | +| **Capacity** | 1) The capability of a system to perform its expected function. 2) The capability of a worker, machine, work center, plant, or organization to produce output per time period. (Source: ASCM Supply Chain Dictionary, 17th edition) | +| **Capacity Group** | The capacity group is the functional entity where material demand and capacity information are matched and compared for the purpose of a collaborative DCM.When the term is written as one word (`WeekBasedCapacityGroup`), the term refers specifically to the respective aspect model. | +| **Actual Capacity** | is the planned available capacity of a supplier, which should be approximately realistic to achieve a material output per calendar week with a certain unit of measurement for one customer. The actual capacity is based on the supplier's assessment of its own capabilities and/or inventories as well as known commitments. | +| **Maximum Capacity** | Is the maximum releasable capacity of a supplier which SHOULD be possible to achieve a material output per calendar week with a certain unit of measurement for one customer. The maximum capacity is based on temporary, capacity-increasing measures, agreed by the parties involved. Capacity-increasing measures can be, for example, a longer utilization of the available production resources, a shift extension or additional shifts. Secondarily, additional resources can also be activated. | +| **Supplier Flex Capacity** | Supplier Flex Capacity = Difference/Area between maximum capacity and actual capacity.Available flex capacity is indicated if the actual capacity still below the maximum capacity. Flex Capacity describes the remaining ability to apply capacity-increasing measures that needs no additionally agreement upon the parties involved. In particular, measures to extend the weekly utilization of the available production resources come into question. | +| **Calendar Week** | A calendar week refers to all 7 days of a week. The counting of the calendar week within a year is based on the Thursday and starts at one ("1") with the week whose Thursday is first in the current year. Example: Week 1 of 2026 = Mon: 29 December 2025, Thu: 01.01.2026, Sun: 4.1.2026. | +| **(Material) demand** | A need for a particular product or component. The demand could come from any number of sources (e.g., a customer order or forecast, an interplant requirement, a branch warehouse request for a service part, or the manufacturing of another product). At the finished goods level, demand data is usually different from sales data because demand does not necessarily result in sales (i.e., If there is no stock, there will be no sale (Source: ASCM Supply Chain Dictionary, 17th edition).Material demand may comprise multiple demand time series by location and demand categories.When the term is written as one word (`WeekBasedMaterialDemand`), the term refers specifically to the respective aspect model. | +| **Bottleneck** | A facility, function, department, or resource whose capacity is less than the demand placed upon it. For example, a bottleneck machine or work center exists where jobs are processed at a slower rate than they are demanded (Source: ASCM Supply Chain Dictionary, 17th edition) | +| **Surplus (capacity)** | A situation in which an oversupply exists (Source: ASCM Supply Chain Dictionary, 17th edition). For example, a machine or work center exists where jobs could be processed, but demand does not require them. | + +Additional terminology used in this standard can be looked up in the glossary on the association +homepage. + +## 2 MAIN CONTENT + +> *This section is normative* + +### 2.1 Contextual Description + +The DCM process REQUIRES the following fundamental steps: + +- Material demands made available by a customer +- Capacities made available by a supplier +- Capacity groups created as an entity, where material demands and capacities are matched and + compared +- A business application that supports the fundamental steps above mentioned + +The data required to run these steps MUST be always up-to-date and shared among involved partners in +a direct business relationship (customers and suppliers) in order to enable a comparison process and +start the collaborative approach, in case of need – for details see Chapter +[2.7](#27-comparison-of-demand-and-capacity-data-within-a-capacity-group) + +### 2.2 Actors and Roles + +The DCM core business logic considers three general actors: the customer, the supplier and the +business application provider. Please be aware, that an individual business partner may have several +direct one-to-one business relationships in which he will act in different roles. For instance, in +one to one business relationship the business partner may act in the role of a customer of his +suppliers. In a different business relationship, he may act as a supplier to his customers. All +actors might have different role titles, depending on their respective organizational structures. +However, all have specific responsibilities and requirements: + +| **Actors** | **Description** | +| --- | --- | +| **Customer** | is a business partner that provides a demand forecast to and receives goods from his supplier. As such, a customer is responsible for providing consistent and up-to-date demand and this role is also a data consumer in regard to capacity data. | +| **Supplier** | is a business partner that supplies goods to a customer. As such, a supplier is responsible for providing consistent and up-to-date capacity and this role is also a data consumer in regard to demand data. | +| **Business application provider** | is a party that provides and operates an application / tool which enables demand and capacity management and follows the core business logic and other standards as described in this document. | + +Examples of typically impacted roles on **customer** side are: + +- Demand Planner +- Supplier Capacity Manager +- Logistic Planner/Manager +- Buyer + +Examples of typically impacted roles on **supplier** side are: + +- Production / Supply Planner +- Demand Planner +- Product Manager +- Sales Manager/Customer Service + +Examples of typically impacted roles on **business application provider** side are: + +- Solution / Product Manager +- Developer +- System Architect +- Operations Manager / Responsible +- Support Engineer + +### 2.3 Process Representation + +![Figure.1.png](./assets/Figure.1.png) +*Figure 1: Process Chart DCM* + +Process details can be retrieved in Annex [Figures](#figures). + +### 2.4 Prerequisites for a Collaborative Demand and Capacity Management + +The following functional prerequisites MUST be met before starting data exchange: + +- Customer and supplier are registered in the Catena-X network and follow the Catena-X guidelines +- Customer and supplier are in a contractual relationship with each other. Among other things, they + MUST agree on a common unit of measure (see Annex [Tables](#tables)) defined at product level to + be used for data exchange purposes (e.g. demand & capacities) +- Both parties are technically able to participate within the DCM process with their respective + business application + +Based on these prerequisites, the exchange of demand and capacity data is enabled. + +### 2.5 Provisioning Demand Data to Supplier + +#### 2.5.1 Detailed Description of Demand + +A customer provides demand data and respective changes to the supplier, who is responsible for +producing/manufacturing and delivering the material to the customer. Thereby, the customer is acting +as a data provider and the supplier as a data consumer of the exchanged material demand. + +The supplier MUST be able to receive the material demand from the customer. + +A demand reflects the need for a particular product or part or component for a certain period of +time. + +The customer owns and MUST publish its own demand with its supplier for the future horizon and it is +highly RECOMMENDED to avoid any gaps as far as possible and to share demand data at least till month +9, to ensure DCM participants to have also sufficient demand data to work with. + +If more demand data is available (i.e. demand related to a horizon that spans beyond month 9), the +customer MAY ideally provide them until month 24. If a customer has even more demand data available +(i.e. demand related to a horizon that spans beyond month 24), he MAY also provide this to his +supplier. + +The data series MAY start already from week *n+2*. + +Although the data series MAY start already from week *n+2* and can be elaborated from a technical +perspective, the DCM process have a clear focus on the tactical mid- to long-term horizon (typically +considered from month 4 to 24) to enable a more resilient supply chain. + +For further technical details refer to chapter "2.2.2 Data Exchange" of the API standard \[[CX-0048](#31-normative-references)] + +CustomersMUST follow the below mentioned guidelines (to be applied along the entire Supply Chain) to +deliver real demand data with high qualityand enable an efficient demand vs. capacity comparison: + +- Demand quantities MUST refer to a period of one calendar week (weekly buckets) +- Demands MUST be considered that are not yet fixed, but related to "opportunities" (e.g. projects) + that will realistically materialize as single-orders + +![Figure.2.png](./assets/Figure.2.png) +Figure 2: Visualized example for Demand Data* + +- Demand data & quantities MUST refer to one of the categories defined in the following table: + +| **Demand Category** | **Description** | **Demand Category Code**** (Based on Data Model)** | +| --- | --- | --- | +| Default | No Assignment | 0001 | +| After-Sales | After sales demand of spare parts | A1S1 | +| Series | Dependent demand e.g. production, assembly, raw material | SR99 | +| Phase-In-period | Ramp up of a new product or new material introduction | PI01 | +| Single-Order | Demand outside the normal spectrum of supply | OS01 | +| Small series | Short time frame for demand and pose to higher volatility | OI01 | +| Extraordinary demand | Temporary demand on top of standard demand | ED01 | +| Phase-Out-period | Ramp down. Product or material retires from the market. | PO01 | + +- Demand MUST be consistent with other exchanged data e.g. call-offs/scheduling agreements +- Material demands data MUST be updated and provided to supplier, whenever changes apply + +For technical details for implementing these demand categories refer to \[[CX-0047](#31-normative-references)]. + +Further guidelines MAY apply: + +- Updating of demand data SHOULD be carried out at least once a month at a certain date or point in + time during the month +- Unnecessary demand fluctuation SHOULD be avoided or limited, because a stable demand plan enables + better capacity planning + +#### 2.5.2 Material Demand Structure + +A material demand data set consists of information about the material itself and the related +customer vs. supplier relationship and more detailed information about the requested quantities per +time period (demand series). + +The picture below illustrates the material demand structure in a simplified way: + +![Figure.3.png](./assets/Figure.3.png) +*Figure 3: Simplified Material Demand Structure* + +For further details refer to the semantic model standard document CX-0047 DCM Data Model +MaterialDemand & CapacityGroup. + +In the next picture it is exemplified how the different material demand information MAY be +visualized, whereas the data can be differentiated between **"header data"** and **"time series +data"** : + +![Figure.4.png](./assets/Figure.4.png) +*Figure 4: Visualized example of a material demand structure* + +#### 2.5.3 Data Model Week Based Material Demand + +For a detailed description of the material demand attributes and material demand series, please +refer to the \[[CX-0047](#31-normative-references)] and \[[CX-0048](#31-normative-references)] standards. + +### 2.6 Provisioning Capacity Data to Customer + +#### 2.6.1 Detailed Description of Capacity Data + +The supplier MUST publish capacity data to the customer, referring to material demand data shared. +Thereby, the supplier is acting as a data provider and the customer as a data consumer of the +exchanged capacity group. + +The customer MUST be able to receive the capacity group incl. the capacity information. + +Capacity information MUST be used as follows: + +- the **"actual capacity"** is the planned available capacity of a supplier +- and the **"maximum capacity**" is the maximum releasable capacity of a supplier (it MAY be equal + or MAY be larger than the "actual capacity" but MUST NOT be smaller than actual capacity) +- When the maximum capacity is larger than the "actual capacity", the difference is called + **"flexible capacity".** + +For further technical details refer to chapter "3.2.2 Data Exchange" of the API standard \[[CX-0048](#31-normative-references)]. + +For a detailed description of these capacity definitions please refer to TERMINOLOGY. + +The picture below illustrates and exemplifies: + +- The black line illustrates the actual capacity +- The dotted grey line illustrates the maximum capacity +- The difference between the two lines is understood as "flexible capacity" + +![Figure.5.png](./assets/Figure.5.png) +*Figure 5: Visualized example of Capacity Data* + +#### 2.6.2 Capacity Group structure + +The capacity group is the entity where material demand and capacity information are matched and +compared for the purpose of a collaborative DCM. Thereby, the capacity group builds the common view +on the data exchanged with each other. The entity capacity group MAY be used, for example, as a +means to combine capacities related to one or more machines, facilities or plants. + +The supplier that uses the capacity group MUST link at least one material demand time series +information to it, however often several material demand information are linked. This builds up the +foundation to reflect the corresponding capacity situation of the supplier. + +![Figure.6.png](./assets/Figure.6.png) +*Figure 6: Visualized example for possible assignments of material demand time series to capacity groups* + +This functional capacity group is technically handled via the so-called aspect model `WeekBasedCapacityGroup`. + +The aspect model `WeekBasedCapacityGroup` MUST be used by a supplier to provide capacity information +to the customer. + +For further details refer to the semantic model standard \[[CX-0047](#31-normative-references)]. + +![Figure.7.png](./assets/Figure.7.png) +*Figure 7: Simplified WeekBasedCapacityGroup structure* + +Data is exchanged via two different aspect models (`WeekBasedMaterialDeman`d and +`WeekBasedCapacityGroup`) between two partners. A partner with role of supplier could send a +capacity group to his partner in role of customer and it is important to understand on which data +elements the linked demand series in the capacity group MUST be included in the solution of the +customer to ensure that the same demand series are considered: + +- supplier +- customer +- CustomerMaterialNumber +- customerLocation +- DemandCategory + +In case there is no (complete) matching of data between supplier and customer it is highly +recommended to start collaboration outside the business application. + +#### 2.6.3 Data Model Week based Capacity Group + +For a detailed description of the capacity group attributes and data, please refer to the +\[[CX-0047](#31-normative-references)] and \[[CX-0048](#31-normative-references)] standards. + +### 2.7 Comparison of Demand and Capacity Data within a Capacity Group + +Based on the aggregated demands, the capacity data will be matched, and a comparison started. This +approach allows partners to timely identify imbalances (e.g. demands are higher than capacities +and/or demands are lower than capacities) and facilitates solving those imbalances, utilizing the +already shared data. The following picture exemplifies this process: + +![Figure.8.png](./assets/Figure.8.png) +*Figure 8: Process Chart DCM* + +#### 2.7.1 Matching Results and Resolution + +Based on the `WeekBasedCapacityGroup` and `WeekBasedMaterialDemand` aspect models, each supplier and +customer MUST apply the same logic when comparing the demand with the corresponding capacity values +to ensure that the matching results are interpreted in the same way. + +For a better understanding the table below describes all scenarios that may apply in a business +context. + +Business application provider, data provider or data consumer MUST enable their DCM system to +recognize the matching situation based on the table below and MUST be able to interpret the matching +result accordingly. The DCM system MAY visualize the matching result in a respective color as well, +based on the example below. + +| **Scenarios** | **Matching situations (MUST)** | **Matching result (MUST)** |**Color coding for example picture below (MAY)** | +| --- | --- | --- | --- | +| 1 | **Demand \> actual capacity (only in case no maximum capacity is applied)** | Bottleneck is identified | red | +| 2 | **Demand \> maximum capacity** | Bottleneck is identified | red | +| 3 | **Demand \> actual capacity \< maximum capacity** | Bottleneck is identified | red | +| 4 | **Demand = actual capacity = maximum capacity** | Zero deviation | green | +| 5 | **Demand \< actual capacity** | a surplus capacity is identified | green | +| 6 | **Demand = actual capacity \< maximum capacity** | Zero deviation | green | + +For a better understanding of how this can be displayed in a DCM system, we provide the example +below, even if it is not exhaustive. + +![Figure.9.png](./assets/Figure.9.png) +*Figure 9: Visualized example of Demand and Capacity Data Matching and Comparison* + +In case a bottleneck or surplus is identified, a DCM collaborative alignment between customer and +supplier is highly RECOMMENDED. + +### 2.8 EDC Policies + +A central part of managing business partner relationships within Catena-X is the definition and +appliance of EDC policies, which enable and protect data exchange. Customer and supplier MUST be +technically able to apply these policies in order to enable a secure collaborative data exchange. + +DCM relies on the following policies: + +| **Category** | **Policy Name** | **Description** | **Variables** | +| --- | --- | --- | --- | +| **Access Policy** | Limit access to the data offered to a list of specified BPNs (to the connectors with the BPN attribute listed in the policy) | This and any other policy which are based on attributes stored in DAPS can be enforced by the connector. So, if a connector is registered in DAPS with attributes such as BPN, Recycler, Germany, an access policy based on any combination of these attributes can be defined and technically enforced by the EDC | | +| **Access Policy** | Country-restricted Data Usage | The usage of the data is only allowed in a specific country. | ISO Country Code as defined in \[[ISO3166](#32-non-normative-references)] | +| Usage Policy | Duration-restricted data policy | This policy specifies for how long the data contract is valid. After the expiry of the data contract, no data exchange under the conditions of this contract can take place. Since the connector is aware of when the contract was electronically signed, it can monitor the validity period and can invalidate the contract. | | +| Usage Policy | Role-restricted data policy | These are the policies that require each use case to define their own set of "roles" such as quality engineer etc. These policies can only be enforced by the consumer applications. Note: keep in mind that this policy is different from any future access policy(ies) that would rely on a role of a company (such as Recycler). These roles, just like the BPN-based access policy, can be enforced by the connector | | +| Usage Policy | Purpose-restricteddata policy | These are the policies that require each use case to define their own set of "purposes" such as "CO2 emissions" etc. These policies can only be enforced by the consumer applications. | | +| **Usage Policy** | Deletion Usage Policy | The data is deleted after a specific time of access / usage. One has to keep in mind that the consumer cannot be expected to delete all potentially effected data backups or database recovery systems. | | +| **Modification Data** | Modify Data (in Transit) | Prohibits data modification in transit. There might be cases where data MUST be modified or e.g. partially anonymized before it is allocated to the user. The data modification MUST be done before permission to use the data is granted. | | +| **Modification** | Modify Data (in Rest) | Prohibit data modification in rest. It demands the modifications to be done when data is stored, for example in a database. The Data Consumer is only allowed to use the data after certain modifications have been applied to the stored data. | | + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +[CX-0001] EDC Discovery API, Version 1.0.1 + +[CX-0003] SAMM Aspect Meta Model, Version 1.0.1 + +[CX-0006] Registration and initial onboarding, Version 1.1.1 + +[CX-0010] Business Partner Number, Version 1.0.1 + +[CX-0015] IAM & Access Control Paradigm, Version 1.0.1 + +[CX-0018] Eclipse Data Space Connector (EDC), Version 1.0.1 + +[CX-0047] Demand and Capacity Management Data Models, Version 1.0.0 + +[CX-0048] Demand and Capacity Management APIs, Version 1.0.0 + +### 3.2 NON-NORMATIVE REFERENCES + +[ISO3166] ISO 3166 Country Codes + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +Following figures describes the complete DCM process, with respect to main actors/roles and +responsibilities. + +![Figure.Annex.png](./assets/Figure.Annex.png) + +### TABLES + +> *This section is non-normative* + +1. Unit of Measure + +| **Dimension** | **UN Code** | **Description (English)** | **Description (German)** | **UN Symbol** | **C-X Symbol** | +| --- | --- | --- | --- | --- | --- | +| **Mass** | GRM | gram | Gramm | g | g | +| **Mass** | KGM | kilogram | Kilogramm | kg | kg | +| **Mass** | TNE | metric ton | Metrische Tonne | t | t | +| **Mass** | STN | ton (US) or short ton (UK/US) | US Tonne | ton (US) | ton | +| **Mass** | ONZ | ounce | Unze | oz | oz | +| **Mass** | LBR | pound | Pfund | lb | lb | +| **Length** | CMT | centimetre | Zentimeter | cm | cm | +| **Length** | MTR | metre | Meter | m | m | +| **Length** | KTM | kilometre | Kilometer | km | km | +| **Length** | INH | inch | Zoll | in | in | +| **Length** | FOT | foot | Fuß | ft | ft | +| **Length** | YRD | yard | Yard | yd | yd | +| **Area** | CMK | square centimetre | Quadrat-zentimeter | cm2 | cm2 | +| **Area** | MTK | square metre | Quadratmeter | m2 | m2 | +| **Area** | INK | square inch | Quadratzoll | in2 | in2 | +| **Area** | FTK | square foot | Quadratfuß | ft2 | ft2 | +| **Area** | YDK | square yard | Quadratyard | yd2 | yd2 | +| **Volume** | CMQ | cubic centimeter | Kubikzentimeter | cm3 | cm3 | +| **Volume** | MTQ | cubic meter | Kubikmeter | m3 | m3 | +| **Volume** | INQ | cubic inch | Kubikzoll | in3 | in3 | +| **Volume** | FTQ | cubic foot | Kubikfuß | ft3 | ft3 | +| **Volume** | YDQ | cubic yard | Kubikyard | yd3 | yd3 | +| **Volume** | MLT | millilitre | Millimeter | ml | ml | +| **Volume** | LTR | litre | Liter | l | l | +| **Volume** | HLT | hectolitre | Hektoliter | hl | hl | +| **Quantum** | H87 | piece | Stück | - | pc | +| **Quantum** | SET | set | Satz | - | set | +| **Quantum** | PR | pair | Paar | - | pr | +| **Quantum** | ZP | page | Blatt | - | pg | +| **Mechanic** | KWH | kilowatt hour | Kilowattstunde | kW·h | kwh | +| **(blank)** | | | | | xxx | + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.1.png b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.1.png new file mode 100644 index 000000000..1388bde5f Binary files /dev/null and b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.1.png differ diff --git a/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.2.png b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.2.png new file mode 100644 index 000000000..cd00be095 Binary files /dev/null and b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.2.png differ diff --git a/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.3.png b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.3.png new file mode 100644 index 000000000..536882528 Binary files /dev/null and b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.3.png differ diff --git a/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.4.png b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.4.png new file mode 100644 index 000000000..f76ef48f0 Binary files /dev/null and b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.4.png differ diff --git a/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.5.png b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.5.png new file mode 100644 index 000000000..fe65b91ac Binary files /dev/null and b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.5.png differ diff --git a/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.6.png b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.6.png new file mode 100644 index 000000000..cdc98d5bb Binary files /dev/null and b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.6.png differ diff --git a/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.7.png b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.7.png new file mode 100644 index 000000000..ae24f1109 Binary files /dev/null and b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.7.png differ diff --git a/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.8.png b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.8.png new file mode 100644 index 000000000..1388bde5f Binary files /dev/null and b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.8.png differ diff --git a/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.9.png b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.9.png new file mode 100644 index 000000000..4bb9be25c Binary files /dev/null and b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.9.png differ diff --git a/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.Annex.png b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.Annex.png new file mode 100644 index 000000000..198d8defd Binary files /dev/null and b/docs/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/assets/Figure.Annex.png differ diff --git a/docs/standards/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup.md b/docs/standards/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup.md new file mode 100644 index 000000000..272707dd2 --- /dev/null +++ b/docs/standards/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup.md @@ -0,0 +1,454 @@ +# CX-0047 Demand and Capacity Management Data Model Material Demand and Capacity Group v1.0.0 + +## DISCLAIMER REGARDING DEMAND AND CAPACITY MANAGEMENT DATA EXCHANGE + +This document describes and standardizes certain data exchange business processes, data models +and/or APIs in connection with cross-company demand and capacity management (DCM) based on the +Catena-X data ecosystem. Nothing in this document is meant to determine the contractual terms and +conditions for the purchase, supply, delivery or licensing of any products or services among the +participants of the DCM data exchange. These terms and conditions are separately negotiated and +agreed among suppliers and customers in individual purchase, supply or license agreements. +In case of any inconsistencies with the content of this document, the provisions of individual +agreements among the participants shall prevail over the content of this document. + +## ABSTRACT + +For cross-company demand and capacity management (DCM), the exchange of demand and capacity +information is the foundation. The demand information describes the material-demand of a company and +is send to a supplier, in order to tell the supplier which materials and how many of them are needed +in a given calendar week. The capacity group is sent from the supplier to the customer in order to +communicate the production capacity for a specific material in a specific calendar week. + +In this document, the data model of the material demand and capacity group information is described +and standardized. There are two separate data models, as the information has a different meaning and +because of the split business responsibilities within DCM. + +The cross-company interactions required during the demand and capacity management process together +with the corresponding common business logic are standardised in \[[CX-0046](#41-normative-references)], +while the APIs are standardized in \[[CX-0048](#41-normative-references)]. + +## 1. INTRODUCTION + +This document describes the `WeekBasedMaterialDemand` and `WeekBasedCapacityGroup` semantic models +used in the Catena-X network. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for: + +- **Data Provider / Consumer** +- **Business Application Provider** + +The `WeekBasedMaterialDemand` object will be send by customers to their suppliers in order to +communicate how many parts they need in which period of time. The customers of materials therefore +need to be able to create `WeekBasedMaterialDemand` objects and the suppliers need to be able to +interpret them. As most suppliers have their own suppliers, who produce materials for them, most +suppliers are therefore acting as customers as well and need to be able to also create +WeekBasedMaterialDemand objects on for sending them to their suppliers. + +The `WeekBasedCapacityGroup` object is sent by the suppliers to their customers to communicate which +materials are bundled together, representing a common bottleneck. And what the capacity for these +materials is, considering their common bottleneck.This information is represented as weekly buckets +within the WeekBasedCapacityGroup. Therefore, all companies, that supply materials to other +companies, need to be able to create `WeekBasedCapacityGroup` objects in a consistent and +standardized structure and send them to their customers. The customers need to be able to receive +and interpret the `WeekBasedCapacityGroup` information. + +The underlying business process is described and standardized in \[[CX-0046](#41-normative-references)]. + +This document only describes the structure of the data model in order to exchange demand and +capacity information. Further information regarding processing or the interface will be described in +\[[CX-0048](#41-normative-references)]. + +### 1.2 CONTEXT + +> *This section is non-normative* + +This standardization defines the `WeekBasedMaterialDemand` and the `WeekBasedCapacityGroup` data +models for the Catena-X network. This standard ensures that the demand and capacity information can +be consumed through the Catena-X network by all customers and suppliers and ensures, that the data +objects from different customers can be handled and interpreted in an identical manner. + +The underlying business process is described and standardized in \[[CX-0046](#41-normative-references)]. + +In this document the `WeekBasedMaterialDemand` data models and `WeekBasedCapacityGroup` data model +are described and standardized to ensure a consistent data exchange structure within the DCM +participants. Thereby an identical interpretation of the data across companies is ensured. + +### 1.3 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, +**SHOULD** and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 +[RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +### 1.4 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to prove, that they are conform with the Catena-X +standards. To validate that the standards are applied correctly, Catena-X employs Conformity +Assessment Bodies (CABs). + +The proof of conformity for a single semantic model is done according to the general rules for +proving the conformity of data provided to a semantic model or the ability to consume the +corresponding data. + +### 1.5 EXAMPLES + +In this chapter, examples for the value-only serialization of `WeekBasedMaterialDemand` and +`WeekBasedCapacityGroup` payloads in JSON format are listed for reference. +The attributes are described further in \[[CX-0046](#41-normative-references)]. +Note that the values in *\{\{brackets\}\}* need to be replaced with actual valid values. + +#### 1.5.1 `WeekBasedMaterialDemand` data model JSON structure + +```json +// value-only payload serialization example +{ + "unitOfMeasure": "GRM", + "materialDescriptionCustomer": "Spark Plug", + "materialDemandId": "0157ba42-d2a8-4e28-8565-7b07830c1110", + "materialNumberSupplier": "MNS-8101-ID146955.001", + "supplier": "{{CATENAX-BUSINESS-PARTNER-NUMBER}}", + "changedAt": "2023-03-08T11:01:02.085+01:00", + "demandSeries": [ + { + "expectedSupplierLocation": "{{CATENAX-SUPPLIER-BPNS}}", + "demands": [ + { + "demand": 1, + "calendarWeek": "2022-03-13" + }, + { + "demand": 1, + "calendarWeek": "2022-03-20" + } + ], + "customerLocation": "{{CATENAX-CUSTOMER-BPNS}}", + "demandCategory": { + "demandCategoryCode": "0001" + } + } + ], + "materialNumberCustomer": "MNC-7307-AU340474.002", + "customer": "{{CATENAX-SUPPLIER-BPNL}}" +} +``` + +#### 1.5.2 `WeekBasedCapacityGroup` data model JSON structure + +```json +// value-only payload serialization example +{ + "unitOfMeasure": "GRM", + "linkedDemandSeries": [ + { + "materialNumberCustomer": "MNC-7307-AU340474.002", + "materialNumberSupplier": "MNS-8101-ID146955.001", + "customerLocation": " {{CATENAX-CUSTOMER-BPNS}}", + "demandCategory": { + "demandCategoryCode": "0001" + } + } + ], + "supplier": "{{CATENAX-BUSINESS-PARTNER-NUMBER}}", + "name": "Spark Plugs on drilling machine for car model XYZ", + "supplierLocations": [ + "{{CATENAX-SUPPLIER-BPNS}}" + ], + "capacities": [ + { + "calendarWeek": "2023-03-13", + "actualCapacity": 1, + "maximumCapacity": 2 + }, + { + "calendarWeek": "2023-03-20", + "actualCapacity": 1, + "maximumCapacity": 2 + } + ], + "changedAt": "2023-03-08T11:44:27.701+01:00", + "capacityGroupId": "0157ba42-d2a8-4e28-8565-7b07830c1110", + "customer": "{{CATENAX-SUPPLIER-BPNL}}" +} +``` + +### 1.6 TERMINOLOGY + +> *This section is non-normative* + +Aspect Model +: a formal, machine-readable semantic description (expressed with RDF/turtle) of data +accessible from an Aspect. + +: *Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it +utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model.* + +: *Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing).* + +: *[Source: Catena-X, CX-0002, note 3 removed]* + +Additional terminology used in this standard can be looked up in the glossary on the association +homepage. + +## 2 ASPECT MODEL “WeekBasedMaterialDemand” + +> *This section is normative* + +### 2.1 INTRODUCTION + +The material demand information MUST be sent from the customer to the supplier according to the +\[[CX-0048](#41-normative-references)] standard. The data format described here MUST be followed for +the exchange of the `WeekBasedMaterialDemand` information. + +The `WeekBasedMaterialDemand` data model MUST be implemented by all participants who wish to +participate in the Catena-X DCM network as a customer or supplier. + +Companies, who participate in the Catena-X Network as a supplier, MUST be able to receive material +demand information and MUST be able to send capacity group information. + +Companies, who participate in the Catena-X Network as a customer, MUST be able to send material +demand information and MUST be able to receive capacity group information. + +Companies who participate in the Catena-X Network with both roles therefore MUST be able to receive +and send both, material demand as well as capacity group information. It is recommended that +companies implement both standards. + +Every data provider of `WeekBasedMaterialDemand` data MUST provide the data conformant to the +semantic model specified in this document. + +The unique identifier of the semantic model specified in this document MUST be used by the data +provider to define the semantics of the data being transferred. + +Every certified business application relying on `WeekBasedMaterialDemand` data MUST be able to +consume data conformant to the semantic model specified in this document. + +This semantic model MUST be made available in the central Semantic Hub. + +Data consumers and data provider MUST comply with the license of the semantic model defined in +[Chapter 2.3](#23-license). + +In the Catena-X data space `WeekBasedMaterialDemand` data MUST be requested and exchanged via +Eclipse Dataspace Connector (EDC) conformant to \[[CX-0018](#41-normative-references)] and \[[CX-0002](#41-normative-references)]. + +The JSON Payload of data providers MUST be conformant to the JSON Schema as specified in this +document. + +The characteristics BPNL and BPNS MUST be used according to the standard \[[CX-0010](#41-normative-references)]. + +### 2.2 SPECIFICATION ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the +"semantic driven workflow" to create a submodel template specification \[[SMT](#42-non-normative-references)]. + +This aspect model is written in SAMM 2.0.0 as a modeling language conformant to \[[CX-0003](#41-normative-references)] +as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to \[[CX-0003](#41-normative-references)]. + +### 2.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +### 2.4 IDENTIFER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + urn:bamm:io.catenax.week_based_material_demand:1.0.0 +``` + +This identifier MUST be used by the data provider to define the semantics of the data being +transferred. + +### 2.5 FORMATS OF SEMANTIC MODEL + +#### 2.5.1 RDF Turtle + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating +additional file formats and serializations. + +```text + https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.week_based_material_demand/1.0.0/WeekBasedMaterialDemand.ttl +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +#### 2.5.2 JSON Schema + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +#### 2.5.3 aasx + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to +\[[SMT](#42-non-normative-references)]. + +Note: As soon as the specification V3.0 of the Asset Administration Shell specfication is available +an update will be provided. + +### 2.6 SEMANTIC MODEL + +Not applicable. + +## 3 ASPECT MODEL "WeekBasedCapacityGroup" + +> *This section is normative* + +### 3.1 INTRODUCTION + +The capacity group information MUST be sent from the supplier to the customer according to the +\[[CX-0048](#41-normative-references)] standard. The data format described here MUST be followed for +the exchange of the capacity group information. + +The capacity group endpoint MUST be implemented by all participants who wish to participate in the +Catena-X DCM network as a customer or supplier. + +Companies, who participate in the Catena-X Network as a supplier, MUST be able to receive material +demand information and MUST be able to send capacity group information. + +Companies, who participate in the Catena-X Network as a customer, MUST be able to send material +demand information and MUST be able to receive capacity group information. + +Companies who participate in the Catena-X Network with both roles therefore MUST be able to receive +and send both, material demand as well as capacity group information. It is recommended that +companies implement both standards. + +Every data provider of `WeekBasedCapacityGroup` data MUST provide the data conformant to the +semantic model specified in this document. + +The unique identifier of the semantic model specified in this document MUST be used by the data +provider to define the semantics of the data being transferred. + +Every certified business application relying on `WeekBasedCapacityGroup` data MUST be able to +consume data conformant to the semantic model specified in this document. + +This semantic model MUST be made available in the central Semantic Hub. + +Data consumers and data provider MUST comply with the license of the semantic model defined in +[Chapter 3.3](#33-license). + +In the Catena-X data space `WeekBasedCapacityGroup` data MUST be requested and exchanged via Eclipse +Dataspace Connector (EDC) conformant to \[[CX-0018](#41-normative-references)] and \[[CX-0002](#41-normative-references)]. + +The JSON Payload of data providers MUST be conformant to the JSON Schema as specified in this +document. + +The characteristics BPNL and BPNS MUST be used according to the standard \[[CX-0010](#41-normative-references)]. + +### 3.2 SPECIFICATION ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the +"semantic driven workflow" to create a submodel template specification \[[SMT](#42-non-normative-references)]. + +This aspect model is written in SAMM 2.0.0 as a modeling language conformant to \[[CX-0003](#41-normative-references)] +as input for the semantic deriven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to \[[CX-0003](#41-normative-references)]. + +### 3.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +### 3.4 IDENTIFER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + urn:bamm:io.catenax.week_based_capacity_group:1.0.0 +``` + +This identifier MUST be used by the data provider to define the semantics of the data being +transferred. + +### 3.5 FORMATS OF SEMANTIC MODEL + +#### 3.5.1 RDF Turtle + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating +additional file formats and serializations. + +```text + https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.week_based_capacity_group/1.0.0/WeekBasedCapacityGroup.ttl +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +#### 3.5.2 JSON Schema + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +#### 3.5.3 aasx + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#42-non-normative-references)]. + +Note: As soon as the specification V3.0 of the Asset Administration Shell specfication is available +an update will be provided. + +### 3.6 SEMANTIC MODEL + +Not applicable. + +## 4 REFERENCES + +### 4.1 NORMATIVE REFERENCES + +[CX-0002] Digital Twins in Catena-X, Version 1.0.1 + +[CX-0003] SAMM Aspect Meta Model, Version 1.0.1 + +[CX-0010] Business Partner Number, Version 1.0.1 + +[CX-0018] Eclipse Data Space Connector (EDC), Version 1.0.1 + +[CX-0046] Demand and Capacity Management Process & Core Business Logic, Version 1.0.0 + +[CX-0048] Demand and Capacity Management APIs, Version 1.0.0 + +### 4.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +[SMT] How to create a submodel template specification. Guideline. Download from: +https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf + +### 4.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +Not applicable. + +### TABLES + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup.md b/docs/standards/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup.md new file mode 100644 index 000000000..4d399e9a6 --- /dev/null +++ b/docs/standards/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup.md @@ -0,0 +1,801 @@ +# CX-0048 Demand and Capacity Management API Material Demand and Capacity Group v1.0.0 + +## Table of Contents + +## DISCLAIMER REGARDING DEMAND AND CAPACITY MANAGEMENT DATA EXCHANGE + +This document describes and standardizes certain data exchange business processes, data models +and/or APIs in connection with cross-company demand and capacity management (DCM) based on the +Catena-X data ecosystem. Nothing in this document is meant to determine the contractual terms and +conditions for the purchase, supply, delivery or licensing of any products or services among the +participants of the DCM data exchange. These terms and conditions are separately negotiated and +agreed among suppliers and customers in individual purchase, supply or license agreements. +In case of any inconsistencies with the content of this document, the provisions of individual +agreements among the participants shall prevail over the content of this document. + +## ABSTRACT + +For cross-company demand and capacity management (DCM), the exchange of demand and capacity +information is the foundation. The demand information describes the part-demand of a customer and is +send to a supplier, in order to tell the supplier which parts and how many of them are needed in a +given calendar week. The capacity group is sent from the supplier to the customer in order to +communicate the production capacity for a specific material in a specific calendar week. + +In this document, the exchange of the material demand and capacity group information is described +and standardized. + +## 1. INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for: + +- **Data Provider / Consumer** +- **Business Application Providers** (for tools relevant for demand and capacity management processes) + +The `WeekBasedMaterialDemand` object will be sent by customers to their suppliers in order to communicate +how many parts or materials they need in which period of time. The customers of parts therefore need +to be able to create `WeekBasedMaterialDemand` objects and the suppliers need to be able to interpret +them. As most suppliers have their own suppliers, who produce parts for them, most suppliers are therefore +acting as customers as well and need to be able to also create `WeekBasedMaterialDemand` objects for +sending their own demand to their suppliers. + +The `WeekBasedCapacityGroup` object will be sent by suppliers to their customers in order to communicate +the production capacity for a specific part or material in specific period of time. Therefore, all companies +that supply parts or materials to other companies, need to be able to create `WeekBasedCapacityGroup` +objects and send them to their customers. The customers need to be able to receive and interpret the +`WeekBasedCapacityGroup` information. + +The underlying business process is described and standardized in \[[CX-0046](#41-normative-references)]. + +### 1.2 CONTEXT + +> *This section is non-normative* + +In this document the WeekBasedMaterialDemand API and WeekBasedCapacityGroup API are described and +standardized to ensure a consistent data exchange and data consumption through EDC between the DCM +participants. Thereby an identical interpretation of the data across companies is ensured. + +The underlying `WeekBasedMaterialDemand` and `WeekBasedCapacityGroup` data model is standardized in \[[CX-0047](#41-normative-references)]. + +The business process is standardized in \[[CX-0046](#41-normative-references)]. + +### 1.3 ARCHITECTURE OVERVIEW + +> *This section is non-normative* + +General overview: the `WeekBasedMaterialDemand` as well as the `WeekBasedCapacityGroup` is a JSON +string which is sent through EDC. The JSON string is standardized in this document and contains +either `WeekBasedMaterialDemand` or `WeekBasedCapacityGroup` information. + +The standard only describes the sending and receiving of `WeekBasedMaterialDemand` and +`WeekBasedCapacityGroup` through EDC. Both objects are created and handled by applications of the +companies involved, but these applications are not part of the standard. + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**,**REQUIRED**, +**SHOULD** and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 +[RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they are conform with the Catena-X +standards. To validate that the standards are applied correctly, Catena-X employs Conformity +Assessment Bodies (CABs). Please refer to: *[!LINK Conformity Assessment]* for the process of +conformity assessment and certification. + +- An example `WeekBasedMaterialDemand` JSON as created by their solution +- An example `WeekBasedCapacityGroup` JSON as created by their solution +- A proof that their solution can process the example payload JSON as listed below + +In case an assessee wants to get certified +: When requesting assessment +Then the assessee produces a letter affirming that they adhere to this standard +And the letter is signed by person who has full power of attorney + +Note that in a future revision of this standard it is planned to offer descriptions of test sets +including test cases and test data for validating API implementations. + +### 1.6 EXAMPLES + +Example JSON strings for `WeekBasedMaterialDemand` and `WeekBasedCapacityGroup` can be found in the +data model standard \[[CX-0047](#41-normative-references)]. + +### 1.7 TERMINOLOGY + +> *This section is non-normative* + +| **Term** | **Description** | +| --- | --- | +| **Business Partner Number Legal Entity (BPNL)** | A BPNL is the unique identifier of a partner within Catena-X, e.g. a company. | +| **Business Partner Number Site (BPNS)** | A BPNS is the unique identifier of a partner location within Catena-X, e.g. a specific factory of a company. | +| **WeekBasedMaterialDemand** | Refers to the `WeekBasedMaterialDemand` object with the same name from the standard \[[CX-0047](#41-normative-references)]. | +| **WeekBasedCapacityGroup** | Refers to the `WeekBasedCapacityGroup` object with the same name from the standard \[[CX-0047](#41-normative-references)]. | + +For a description of further terms please refer to the data model in the standard \[[CX-0047](#41-normative-references)]. + +Additional terminology used in this standard can be looked up in the glossary on the association +homepage. + +## 2. WeekBasedMaterialDemand API + +> *This section is normative* + +The `WeekBasedMaterialDemand` contains the material demand information which is send from the +customer to the supplier. + +All participants participating in Catena-X DCM in the role of a customer MUST be able to send the +`WeekBasedMaterialDemand`. All participants participating in Catena-X DCM in the role of a supplier +MUST be able to receive and process the `WeekBasedMaterialDemand`. + +## 2.1 PRECONDITIONS AND DEPENDENCIES + +The `WeekBasedMaterialDemand` API MUST be published towards the network using a Data Asset/Contract +Offer in terms of the Dataspace Protocol as defined by IDSA, following the Catena-X standard +SOV-001. + +## 2.2 API SPECIFICATION + +### 2.2.1 API Endpoints & Resources + +To support the exchange of `WeekBasedMaterialDemand` data, a business application MUST define a +single endpoint supporting the HTTP POST request method as described in \[[RFC9110](#42-non-normative-references)]. +The structure of the endpoint MAY be freely chosen. The address of the endpoint MUST be provided +as part of the EDC Data Asset defined in chapter [2.2.5](#225-edc-data-asset-structure) of this document. + +### 2.2.2 Data Exchange + +The WeekBasedMaterialDemand data MUST be sent from the customer to the supplier using an HTTP POST +request. The data format described here MUST be followed for the exchange of the material demand +information. + +Multiple `WeekBasedMaterialDemand` aspects MAY be sent in one transfer as a JSON list. If only one +`WeekBasedMaterialDemand` aspect is transmitted, it MUST still be sent as a list with one entry. + +The serialized JSON MUST NOT be larger than 15 MiB in size. + +The `WeekBasedMaterialDemand` endpoint MUST be implemented by all participants who wish to +participate in the Catena-X DCM network as a supplier. Customers MUST be able to send material +demand objects to their suppliers. + +The data payload itself MUST be a valid JSON string. + +All attributes marked as mandatory in the standard \[[CX-0047](#41-normative-references)] MUST be included +in the dataset. Attributes marked as 'Optional' MAY be included in the data set. + +The usage of the attributes in the data model MUST follow the attribute descriptions in the definitions +in \[[CX-0046](#41-normative-references)]. While some attributes are technically a +string, not any string is valid. For example, expectedSupplierLocations MUST be formatted as a BPNS. + +The calenderWeek MUST be set to a Monday of the week for that specific demand. The date format MUST +be in accordance with \[[ISO8601](#42-non-normative-references)] and MUST be in the format +YYYY-MM-DD (for example 2023-02-13). + +The attributes 'demandCategory' and 'unitOfMeasure' MUST be set to one of the defined values as +defined in the standard \[[CX-0046](#41-normative-references)]. + + > **Definition from \[[CX-0046](#41-normative-references)]** (Standardized there, non-normative +quote here) "*The customer owns and MUST publish its own demand with its supplier for the future +horizon and it is highly RECOMMENDED to avoid any gaps as far as possible and to share demand data +at least till month 9, to ensure DCM participants to have also sufficient demand data to work with.* +*If more demand data is available (i.e. demand related to a horizon that spans beyond month 9), the +customer MAY ideally provide them until month 24. If a customer has even more demand data available +(i.e. demand related to a horizon that spans beyond month 24), he MAY also provide this to his +supplier. The data series MAY start already from week n+2. Although the data series MAY start +already from week n+2 and can be elaborated from a technical perspective, the DCM process have a +clear focus on the tactical mid- to long-term horizon (typically considered from month 4 to 24) to +enable a more resilient supply chain.*" + +In addition to the definitions from \[[CX-0046](#41-normative-references)] quoted above, the following +rules have to be followed: + +The data series in the `WeekBasedMaterialDemand` SHOULD start already from week *n+2*. + +The demand for the current week (*n=0*) and the next week (*n=1*) MAY be included in the dataset. +The `WeekBasedMaterialDemand` MUST include at least one week other than the current or the next week +(meaning it may not be empty). Every week MUST NOT be included multiple times in the same +`WeekBasedMaterialDemand`. + +If the demand for one of the weeks changes, the whole dataset MUST be sent to the supplier; sending +the changes only (delta update / incremental update) is not possible. By this procedure, +inconsistent or incomplete data sets are avoided. One data transfer MUST contain at least one +`WeekBasedMaterialDemand` data set. + +For the combination of the attributes supplier, customer and materialNumberCustomer in the object +`WeekBasedMaterialDemand`, there MUST NOT be more than one `WeekBasedMaterialDemand` object in +existence. This means that the customer needs to collect all demands for all factories and send them +aggregated as one `WeekBasedMaterialDemand` to the supplier. + +If the demand in a certain week has the value `0`, it MUST be explicitly included as such in the +`WeekBasedMaterialDemand`, meaning the week cannot be left out (as there is a difference between +null and 0). Weeks with an unknown demand (value `null`) SHOULD be left out. + +### 2.2.3 UUID generation and handling + +When exchanging demand data, the usage of UUIDv4 is required in order to reduce the probability of +collision as well as to eliminate certain attack vectors. For technical purposes the UUIDv4 MUST be +treated as unique within the supplier-customer relationship. For the combination of attributes: supplier, +customer and materialNumberCustomer in the object `WeekBasedMaterialDemand` there MUST be exactly one +unique UUIDv4. + +The UUIDv4 MUST be generated according to \[[RFC4122](#41-normative-references)]. + +Refer to chapter [2.2.7](#227-validating-payload) for further handling information. + +### 2.2.4 Available Data Types + +The API MUST use JSON as the payload transported via HTTPS. + +### 2.2.5 EDC Data Asset Structure + +The HTTP POST endpoint introduced in chapter [2.2.1](#221-api-endpoints--resources) MUST NOT be +called from a supply chain partner directly. Rather, it MUST be called via an EDC communication. +Therefore, the endpoint MUST be offered as an EDC Data Asset. The latter MUST have a property +`asset:prop:dcm` with value `weekbasedmaterialdemand-endpoint`. This property SHOULD be used to +identify the asset when searching the assets catalog of a supplier. Because the asset reflects the +contractual relationship between a supplier and its customers, only one asset with the +aforementioned property MUST be visible to the customer at any time to avoid ambiguity. + +An example EDC Data Asset definition with a corresponding access / usage policy and contract +definition are shown below. + +>Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +// Asset definition +{ + "asset": { + "properties": { + "asset:prop:id": "1", + "asset:prop:dcm": "weekbasedmaterialdemand-endpoint", + "asset:prop:description": "Endpoint for provisioning of week based material demands" + } + }, + "dataAddress": { + "properties": { + "type": "HttpData", + "baseUrl": "{{ **URL-WEEKBASEDMATERIALDEMAND-ENDPOINT** }}" + } + } +} +``` + +```json +// Access and Usage Policy definition +{ + "id": "1", + "policy": { + "prohibitions": [ + ], + "obligations": [ + ], + "permissions": [ + { + "edctype": "dataspaceconnector:permission", + "action": { + "type": "USE" + }, + "constraints": [ + { + "edctype": "AtomicConstraint", + "leftExpression": { + "edctype": "dataspaceconnector:literalexpression", + "value": "BusinessPartnerNumber" + }, + "rightExpression": { + "edctype": "dataspaceconnector:literalexpression", + "value": "{{ **CUSTOMER-BPN** }}" + }, + "operator": "EQ" + } + ] + } + ] + } +} +``` + +```json +// Contract definition +{ + "id": "1", + "criteria": [ + { + "operandLeft": "asset:prop:id", + "operator": "=", + "operandRight": "1" + } + ], + "accessPolicyId": "1", + "contractPolicyId": "1" +} +``` + +### 2.2.6 Error Handling + +Every API endpoint defined in chapter [2.2.1](#221-api-endpoints--resources) MUST respond to incoming +requests with HTTP status codes as described in \[[RFC9110](#42-non-normative-references)]. +All of the following HTTP status codes, except for codes 200 and 201, MUST be interpreted as failures. +Therefore, it may be sufficient for a business application to simply check if the status +code is 200 or 201 or not. If not, the request failed. + +| **HTTP Status Code** | **HTTP Status Message** | **Description** | +| --- | --- | --- | +| 200 | OK | The request has succeeded. The `WeekBasedMaterialDemand` has been successfully processed in the backend system. | +| 201 | Created | The request has succeeded and has led to the creation of a new `WeekBasedMaterialDemand` in the backend system. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | +| 403 | Forbidden | The `WeekBasedMaterialDemand` in question is not available for the client (e.g. it belongs to a different company) | +| 405 | Method not allowed | The method used to request the data was not POST | +| 422 | Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors, e.g. the JSON payload could not be parsed. | +| 503 | Service Unavailable | + +If one `WeekBasedMaterialDemand` aspect is transmitted in one HTTP request, the return codes MUST be +used as stated in the table above. + +If a list of multiple `WeekBasedMaterialDemand` aspects is transmitted in one HTTP request, the +status code 400 MUST be used if at least one `WeekBasedMaterialDemand` in the list cannot be +processed. Applications MAY choose to process valid entries from a list which also contains invalid +entries. If a list of multiple `WeekBasedMaterialDemand` aspects is transmitted in one HTTP request, +and all of them can be processed successfully, the status code 200 MUST be used. + +The return codes 401, 405, 422 and 503 in the table above MAY also be applicable to a list of +multiple `WeekBasedMaterialDemand` aspects. + +Further status codes may be included in a later revision of this standard. The ability to send and +receive one status code per sent or received list item might be included in a later revision of this +standard. + +### 2.2.7 Validating payload + +The following tables are supposed to answer questions regarding what business logic MUST be executed +when receiving a `WeekBasedMaterialDemand` which has been formed in a specific way. + +A non-normative overview of all rules can be found in \[[PayloadValidationRules](#42-non-normative-references)]. + +The order of rules is indicated by the 'Number' row. The rules MUST be executed in exactly this +order, starting from the lowest number. + +The first rule that matches MUST be executed. All other rules MUST be ignored. + +'value' indicates the actual value written in quotation marks and without any specific formatting +(e.g. italic). + +*Valid value* indicates that the value is valid according to \[[CX-0047](#41-normative-references)] +and \[[CX-0048](#41-normative-references)] (this standard) and \[[CX-0046](#41-normative-references)]. + +*Invalid value* indicates that the value is invalid according to \[[CX-0047](#41-normative-references)] +and \[[CX-0048](#41-normative-references)] (this standard) and \[[CX-0046](#41-normative-references)]. + +*Any value* indicates that the value can by anything, valid or not. + +A whitespace or an empty cell indicates that for this specific rule that row is not applicable. + +| **Number** | 1 | | +| :--- | :---: | :---: | +| **Properties** | | | +| **Meta properties** | Any property | *Invalid value* | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore received values | +| |Return Code | 400 – Bad Request | + +| **Number** | 2 | | +| :--- | :---: | :---: | +| **Properties** | customer | Customer BPNL does not match the sending EDCs registered BPNL | +| **Meta properties** | Any property | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 400 – Bad Request | + +| **Number** | 3 | | +| :--- | :---: | :---: | +| **Properties** | supplier | Supplier does not match any Supplier BPNL that I am responsible for | +| **Meta properties** | Any property | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 400 – Bad Request | + +| **Number** | 4 | | +| :--- | :---: | :---: | +| **Properties** | materialDemandID | *Known value* | +| | changedAt | More recent than all previously received `WeekBasedMaterialDemand` with the same materialDemandID | +| **Meta properties** | Any property | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Overwrite all existing values | +| | Return Code | 200 – OK | + +| **Number** | 5 | | +| :--- | :---: | :---: | +| **Properties** | materialDemandID | *Unknown value*, but there exists another UUID for the exact same combination of supplier, customer and materialNumberCustomer | +| | customer | *Known value* | +| | supplier | *Known value* | +| | materialNumberCustomer | *Known value* | +| **Meta properties** | Any property | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 400 – Bad Request | + +| **Number** | 6 | | +| :--- | :---: | :---: | +| **Properties** | materialDemandID | *Unknown value* | +| **Meta properties** | Any property | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Save as new material demand with received values | +| | Return Code | 201 - Created | + +| **Number** | 7 | | +| :--- | :---: | :---: | +| **Properties** | materialDemandID | *Known value* | +| | changedAt | Older than any previously received `WeekBasedMaterialDemand` with the same materialDemandID | +| **Meta properties** | Any property | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 400 – Bad Request | + +| **Number** | 8 | | +| :--- | :---: | :---: | +| **Properties** | materialDemandID | *Known value* | +| | changedAt | Identical to the most recent of all previously received `WeekBasedMaterialDemand` with the same materialDemandID | +| **Meta properties** | Any property | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Overwrite all existing values with received values | +| | Return Code | 200 – OK | + +## 3. WeekBasedCapacityGroup API + +> *This section is normative* + +The `WeekBasedCapacityGroup` contains the capacity group information which is send from the supplier +to the customer. + +All participants participating in Catena-X DCM in the role of a supplier MUST be able to send the +`WeekBasedCapacityGroup`. All participants participating in Catena-X DCM in the role of a customer +MUST be able to receive and process the `WeekBasedCapacityGroup`. + +## 3.1 PRECONDITIONS AND DEPENDENCIES + +The WeekBasedCapacityGroup API MUST be published towards the network using a Data Asset/Contract +Offer in terms of the Dataspace Protocol as defined by IDSA, following the Catena-X standard +SOV-001. + +## 3.2 API SPECIFICATION + +### 3.2.1 API Endpoints & Resources + +To support the exchange of `WeekBasedCapacityGroup` data, a business application MUST define a +single endpoint supporting the HTTP POST request method as described in \[[RFC9110](#42-non-normative-references)]. +The structure of the endpoint MAY be freely chosen. The address of the endpoint MUST be provided as +part of the EDC Data Asset defined in chapter [3.2.5](#325-edc-data-asset-structure) of this document. + +### 3.2.2 Data Exchange + +The `WeekBasedCapacityGroup` data MUST be sent from the supplier to the customer using an HTTP POST +request. The data format described here MUST be followed for the exchange of the capacity group +information. + +Multiple `WeekBasedCapacityGroup` aspects MAY be sent in one transfer as a JSON list. If only one +`WeekBasedCapacityGroup` aspect is transmitted, it MUST still be sent as a list with one entry. + +The serialized JSON MUST NOT be larger than 15 MiB in size. + +The WeekBasedCapacityGroup endpoint MUST be implemented by all participants who wish to participate +in the Catena-X DCM network as a customer. Suppliers MUST be able to send `WeekBasedCapacityGroup` +objects to their customers. + +The data payload itself MUST be a valid JSON string. + +All attributes marked as mandatory in the standard \[[CX-0047](#41-normative-references)] MUST be +included in the dataset. Attribute marked as 'Optional' CAN be included in the data set. + +The usage of the attributes in the data model MUST follow the attribute descriptions in the standard +\[[CX-0047](#41-normative-references)] and the definitions in \[[CX-0046](#41-normative-references)]. +For example, an exact definition of the different capacities is provided there and needs to be observed. + +While some attributes are technically a string, not any string is valid. For example, supplier MUST +be formatted as a BPNL (see table above). + +The calenderWeek MUST be set to a Monday of the week for that specific `WeekBasedCapacityGroup`. The +date format MUST be in accordance with \[[ISO8601](#42-non-normative-references)] and MUST be in the +format YYYY-MM-DD (for example 2023-02-13). + +The data payload itself MUST be a valid JSON file. + +The attributes 'demandCategory' and 'unitOfMeasure' MUST be set to one of the defined values as +defined in the standard \[[CX-0047](#41-normative-references)]. + +The capacities for the current week (*n=0*) and the next week (*n=1*) MAY be included in the +dataset. The `WeekBasedCapacityGroup` MUST include at least one week other than the current or the +next week (meaning it may not be empty). Every week MUST NOT be included multiple times in the same +`WeekBasedCapacityGroup`. + +If the capacity for one of the weeks changes, the whole dataset MUST be sent to the customer, +sending the changes only (delta update / incremental update) is NOT possible. By this procedure, +inconsistent or incomplete data sets are avoided. One data transfer MUST contain at least one +`WeekBasedCapacityGroup` data set. + +Additional business-process related rules are specified in the 'process template', these MUST be +followed as well. For example, the 'process template' defines a capacity and how it is to be +interpreted or that a demand must be consistent with other exchanged information such as call-offs. +All `WeekBasedCapacityGroup` objects MUST only use a mutually agreed unit of measure (as defined in +the standard \[[CX-0046](#41-normative-references)]). + +The property linkedDemandSeries is used to indicate to which `WeekBasedMaterialDemand` object a +`WeekBasedCapacityGroup` object refers to. More specifically, the linkedDemandSeries refers to a +demand for a specific demandCategory / customerLocation / materialNumberCustomer combination. + +One specific combination of demandCategory / customerLocation / materialNumberCustomer MAY be +referred to in multiple `WeekBasedCapacityGroup` objects. Therefore, one materialNumberCustomer MAY +be contained in linkedDemandSeries of several different `WeekBasedCapacityGroup` objects. + +The order of the entries listed in the linkedDemandSeries of a `WeekBasedCapacityGroup` is arbitrary +and MUST be treated as such. + +### 3.2.3 UUID generation and handling + +When exchanging demand data, the usage of UUIDv4 is required in order to reduce the probability of +collision as well as to eliminate certain attack vectors. For technical purposes the UUIDv4 MUST be +treated as unique within the supplier-customer relationship. + +The UUIDv4 MUST be generated according to \[[RFC4122](#41-normative-references)]. + +Refer to chapter [3.2.7](#327-validating-payload) for further handling information. + +### 3.2.4 Available Data Types + +The API MUST use JSON as the payload transported via HTTPS. + +### 3.2.5 EDC Data Asset Structure + +The HTTP POST endpoint introduced in chapter [3.2.1](#321-api-endpoints--resources) MUST NOT be +called from a supply chain partner directly. Rather, it MUST be called via an EDC communication. +Therefore, the endpoint MUST be offered as an EDC Data Asset. The latter MUST have a property " +**asset:prop:dcm**" with value " **weekbasedcapacitygroup-endpoint**". This property SHOULD be used +to identify the asset when searching the assets catalog of a customer. Because the asset reflects +the contractual relationship between a customer and its suppliers, only one asset with the +aforementioned property MUST be visible to the supplier at any time to avoid ambiguity. + +An example EDC Data Asset definition with a corresponding access / usage policy and contract +definition are shown below. + +>Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +// Asset definition +{ + "asset": { + "properties": { + "asset:prop:id": "1", + "asset:prop:dcm": "weekbasedcapacitygroup-endpoint", + "asset:prop:description": "Endpoint for provisioning of week based capacity groups" + } + }, + "dataAddress": { + "properties": { + "type": "HttpData", + "baseUrl": "{{URL-WEEKBASEDCAPACITYGROUP-ENDPOINT}}" + } + } +} +``` + +```json +// Access and Usage Policy definition +{ + "id": "1", + "policy": { + "prohibitions": [ + ], + "obligations": [ + ], + "permissions": [ + { + "edctype": "dataspaceconnector:permission", + "action": { + "type": "USE" + }, + "constraints": [ + { + "edctype": "AtomicConstraint", + "leftExpression": { + "edctype": "dataspaceconnector:literalexpression", + "value": "BusinessPartnerNumber" + }, + "rightExpression": { + "edctype": "dataspaceconnector:literalexpression", + "value": "{{SUPPLIER-BPN}}" + }, + "operator": "EQ" + } + ] + } + ] + } +} +``` + +```json +// Contract definition +{ + "id": "1", + "criteria": [ + { + "operandLeft": "asset:prop:id", + "operator": "=", + "operandRight": "1" + } + ], + "accessPolicyId": "1", + "contractPolicyId": "1" +} +``` + +### 3.2.6 Error Handling + +Every API endpoint defined in chapter [3.2.1](#321-api-endpoints--resources) MUST respond to incoming +requests with HTTP status codes as described in \[[RFC9110](#42-non-normative-references)]. +All of the following HTTP status codes, except for codes 200 and 201, MUST be interpreted as failures. +Therefore, it may be sufficient for a business application to simply check if the status code is +200 or 201 or not. If not, the request failed. + +| **HTTP Status Code** | **HTTP Status Message** | **Description** | +| --- | --- | --- | +| 200 | OK | The request has succeeded. The `WeekBasedCapacityGroup` has been successfully processed in the backend system. | +| 201 | Created | The request has succeeded and has led to the creation of a new `WeekBasedCapacityGroup` in the backend system. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | +| 403 | Forbidden | The `WeekBasedCapacityGroup` in question is not available for the client (e.g. it belongs to a different company) | +| 405 | Method not allowed | The method used to request the data was not POST | +| 422 | Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors, e.g. the JSON payload could not be parsed. | +| 503 | Service Unavailable | + +If one `WeekBasedCapacityGroup` aspect is transmitted in one HTTP request, the return codes MUST be +used as stated in the table above. + +If a list of multiple `WeekBasedCapacityGroup` aspects is transmitted in one HTTP request, the +status code 400 MUST be used if at least one `WeekBasedCapacityGroup` in the list cannot be +processed. Applications MAY choose to process valid entries from a list which also contains invalid +entries. If a list of multiple `WeekBasedCapacityGroup` aspects is transmitted in one HTTP request, +and all of them can be processed successfully, the status code 200 MUST be used. + +The return codes 401, 405, 422 and 503 in the table above MAY also be applicable to a list of +multiple `WeekBasedCapacityGroup` aspects. + +Further status codes may be included in a later revision of this standard. The ability to send and +receive one status code per sent or received list item might be included in a later revision of this +standard. + +### 3.2.7 Validating Payload + +The following tables are supposed to answer questions regarding what business logic MUST be executed +when receiving a `WeekBasedCapacityGroup` which has been formed in a specific way. + +An overview of all rules can be found in \[[PayloadValidationRules](#42-non-normative-references)]. + +The order of rules is indicated by the 'Number' row. + +The first rule that matches MUST be executed. All other rules MUST be ignored. + +'value' indicates the actual value written in quotation marks and without any specific formatting +(e.g. italic). + +*Valid value* indicates that the value is valid according to \[[CX-0047](#41-normative-references)] +and \[[CX-0048](#41-normative-references)] (this standard) and \[[CX-0046](#41-normative-references)]. + +*Invalid value* indicates that the value is invalid according to \[[CX-0047](#41-normative-references)] +and \[[CX-0048](#41-normative-references)] (this standard) and \[[CX-0046](#41-normative-references)]. + +*Any value* indicates that the value can by anything, valid or not. + +A whitespace or an empty cell indicates that for this specific rule that row is not applicable. + +| **Number** | 1 | | +| :--- | :---: | :---: | +| **Properties** | | | +| **Meta properties** | Any property | *Invalid value* | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 400 – Bad Request | + +| **Number** | 2 | | +| :--- | :---: | :---: | +| **Properties** | supplier | Supplier BPNL does not match the sending EDCs registered BPNL | +| **Meta properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 400 – Bad Request | + +| **Number** | 3 | | +| :--- | :---: | :---: | +| **Properties** | customer | Customer does not match any Customer BPNL that I am responsible for | +| **Meta properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 400 – Bad Request | + +| **Number** | 4 | | +| :--- | :---: | :---: | +| **Properties** | capacityGroupID | *Known value* | +| | changedAt | More recent than all previously received `WeekBasedCapacityGroup` with the same capacityGroupID | +| **Meta properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Overwrite all existing values | +| | Return Code | 200 – OK | + +| **Number** | 5 | | +| :--- | :---: | :---: | +| **Properties** | capacityGroupID | *Unknown value* | +| **Meta properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Save as new capacity group with received values | +| | Return Code | 201 - CREATED | + +| **Number** | 6 | | +| :--- | :---: | :---: | +| **Properties** | capacityGroupID | *Known value* | +| | changedAt | Older than any previously received `WeekBasedCapacityGroup` with the same capacityGroupID | +| **Meta properties** | Any property | | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 400 – Bad Request | + +| **Number** | 7 | | +| :--- | :---: | :---: | +| **Properties** | capacityGroupID | *Known value* | +| | changedAt | Identical to the most recent of all previously received `WeekBasedCapacityGroup` with the same capacityGroupID | +| **Meta properties** | Any property | | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Overwrite all existing values with received values | +| | Return Code | 200 – OK | + +## 4 REFERENCES + +### 4.1 NORMATIVE REFERENCES + +[CX-0046] Demand and Capacity Management Process & Core Business Logic, Version 1.0.0 + +[CX-0047] Demand and Capacity Management Data Models, Version 1.0.0 + +### 4.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +[RFC4122] A Universally Unique IDentifier (UUID) URN Namespace +(https://www.rfc-editor.org/rfc/rfc4122) + +[RFC9110] HTTP Semantics (https://www.rfc-editor.org/rfc/rfc9110) + +[ISO8601] Date and time format + +[PayloadValidationRules] [PayloadValidationRules.xlsx](./assets/PayloadValidationRules.xlsx) + +### 4.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +Not applicable. + +### TABLES + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup/assets/PayloadValidationRules.xlsx b/docs/standards/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup/assets/PayloadValidationRules.xlsx new file mode 100644 index 000000000..28fbe4b87 Binary files /dev/null and b/docs/standards/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup/assets/PayloadValidationRules.xlsx differ diff --git a/docs/standards/CX-0049-DIDDocumentSchema/CX-0049-DIDDocumentSchema.md b/docs/standards/CX-0049-DIDDocumentSchema/CX-0049-DIDDocumentSchema.md new file mode 100644 index 000000000..82333fce1 --- /dev/null +++ b/docs/standards/CX-0049-DIDDocumentSchema/CX-0049-DIDDocumentSchema.md @@ -0,0 +1,217 @@ + +# CX-0049 DID Document v2.0.0 + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +- Re-definition of the structure of the did-document + +## ABSTRACT + +The document describes the structure. the location and the accessability of and the requirements to the `DID document` used for the Identification of Dataspace participants. + +## 1. INTRODUCTION + +The DID document is a fundamental and mandatory element in the context of Self-Sovereign Identity (SSI), as it contains the public key needed for the verification of the participant identity. Having the DID of a participants the location of the DID document can be resolved to get the get both the participants's public key and the list of services in context of it's identity. +As described in CX-0013:2.0 Identity of Dataspace participants, in the context of Catena-X Self-Sovereign Identity (SSI) is used as the identity for Participants. Based on the W3C standard for Decentralized Identifiers (DID) [https://www.w3.org/TR/did-core/], the did is used as the identifier, which points to the DID Document of the participant [https://www.w3.org/TR/did-spec-registries/#did-document-properties]. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +#### AUDIENCE + +This document focuses on the schema of DID documents for the DIDs of Catena-X Dataspace participants. It applies to DIDs issued in the course of registration (CX-0013 - Identity of member companies v2.0.0) as well as to DIDs that already exist at the time of registration with Catena-X. + +This document is relevant for the following roles, as the must be certified against it: + +- Core Service Providers as they offer the registration to the Catena-X network +- Enablement Service Providers which offer Wallet Services to the Core Service Providers + +#### SCOPE + +This document covers the requirements to the DID document used in the context of Catena-X- It describes: + +- The structure of the DID document including mandatory service endpoints and public/private key algorithms +- The location of the DID document +- The resolution of the DID to access the DID document + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +In general the concept of SSI according to the W3C standard [https://www.w3.org/TR/did-core/] is the link between a unique identifier - the Decentralized Identifier (DID) - and the DID document. + +The DID itself does not have to contain any identity features. In this context, the DID document contains a collection of service endpoints and the public keys of the identified participant, which can be used for any cryptographic signature and any type of authentication. For the storage of the DID document, it must be ensured that the document cannot be changed by third parties, as this would enable identity theft through manipulation of the public key. +In the context of SSI, there is no need for a central issuing office for identities. Due to open standards and the associated multitude of providers of DIDs and verifiable credentials, the data sovereignty of the participants in the network is ensured. + +In addition to defined service endpoints, especially for the request for verifiable credentials, the did standard also allows the definition of specific endpoints for context-related services. + +To ensure that the DID of a participant can be used and is accepted by all other participants in the network, but also across networks, the DID document is based on the W3C standard [https://www.w3.org/TR/did-core/#did-documents]. Compliance with the W3C standard for DID documents applies both to DIDs created by Enablement Service Providers of Wallet services in the course of registration. + +### 1.3 ARCHITECTURE OVERVIEW + +> *This section is non-normative* + +Not applicable. + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is non-normative* + +`Core Service Provider` + +A Core Service Provider **MUST** ensure that all dataspace participants have an DID document according to the structure defined in this document. +The Core Service Provider **MUST** ensure that the DID created in the course of registration is resolvable to the created DID document. +A Core Service Provider **MUST** ensure that the DID document is accessible for everyone over http or https. + +To validate these criteria for an own implementation of the Core Service Provider please the following information **MUST** be handed to the Conformity Assessment Body by the Core Service Provider: + +- A documentation (e.g. based on Arc42) explaining the architecture, access management and process flows of the implementation. + +`Enablement Service Provider` + +An Enablement Service Provider providing a Wallet service to a Core Service Provider **MUST** ensure that all Dataspace participants who's DIDs are managed with his Wallet service have an DID document according to the structure defined in this document. +He **MUST** ensure that the DID created in the course of registration is resolvable to the created DID document. +And he also **MUST** ensure that the DID document is accessible for everyone over http or https. + +To validate these criteria for an own implementation of the Core Service Provider the following information **MUST** be handed to the Conformity Assessment Body: + +- A documentation (e.g. based on Arc42) explaining the architecture, access management and process flows of the implementation. + +To validate these criteria of conformance of the DID Document to the DID Document schema the following information **MUST** be handed to the Conformity Assessment Body: + +- A documentation (e.g. based on Arc42) explaining the architecture, process flows, the data structures and storage infrastructure of the solution. + +### 1.6 TERMINOLOGY + +> *This section is non-normative* + +Not applicable. + +## 2. DID DOCUMENT + +The following DID document uses a kind of real data to present a better readable example of it's structure. +For Release 24.05 the accepted DID Method for all participant's DIDs is `did:web` method defined here: +https://w3c-ccg.github.io/did-method-web/ + +```text +Disclaimer: + +In future releases it will be possible for every participant to use his existing DID, managed by his own wallet, for the registration to Catena-X. This will also include the usage of other DID methods than `did:web`. +``` + +### 2.1 VERIFICATION METHOD + +The used verification method for the created DID documents of the participants is `JsonWebKey2020` + +### 2.2 DID DOCUMENT STRUCTURE + +> *This section is normantive* + +The DID document for the Decentralized Identifiers provided by all Catena-X members **MUST** be created according to the following structure + +```json +{ + "@context":[ + "https://www.w3.org/ns/did/v1" + ], + "id":"did:web:ica-catena-x-dim-consumer-dev-dev-dis-diddoc.cfapps.eu12.hana.ondemand.com:user:issuer", + "verificationMethod":[ + { + "id":"did:web:ica-catena-x-dim-consumer-dev-dev-dis-diddoc.cfapps.eu12.hana.ondemand.com:user:issuer#keys-2120c0bb-e72f-4e1a-8d14-0b3480afbdc6", + "type":"JsonWebKey2020", + "controller":"did:web:ica-catena-x-dim-consumer-dev-dev-dis-diddoc.cfapps.eu12.hana.ondemand.com:user:issuer", + "publicKeyJwk":{ + "kty":"EC", + "crv":"secp256k1", + "x":"608KKIEIupnefu502gmZMv2SMOUpYFB7w5VniJIMDlg", + "y":"aD7P3H-PCtSjxGPYhRqpjl12QtK-e0qaPI7AFy3v5KQ" + } + }, + { + "id":"did:web:ica-catena-x-dim-consumer-dev-dev-dis-diddoc.cfapps.eu12.hana.ondemand.com:user:issuer#keys-768f94e5-67b2-464f-a1de-e2beb9828aed", + "type":"JsonWebKey2020", + "controller":"did:web:ica-catena-x-dim-consumer-dev-dev-dis-diddoc.cfapps.eu12.hana.ondemand.com:user:issuer", + "publicKeyJwk":{ + "kty":"EC", + "crv":"secp256k1", + "x":"NT_jO4J7ljC0oyZiO4ffp_igIZ5EYZMgICIoO54T2HE", + "y":"YnH3cpAFyGcfiX1v1HBEYgJhVO3TajqTV-CbXOi-MT8" + } + } + ], + "authentication":[ + "did:web:ica-catena-x-dim-consumer-dev-dev-dis-diddoc.cfapps.eu12.hana.ondemand.com:user:issuer#keys-2120c0bb-e72f-4e1a-8d14-0b3480afbdc6", + "did:web:ica-catena-x-dim-consumer-dev-dev-dis-diddoc.cfapps.eu12.hana.ondemand.com:user:issuer#keys-768f94e5-67b2-464f-a1de-e2beb9828aed" + ], + "service":[ + { + "id":"did:example:1701379495100", + "type":"DIDMessaging", + "serviceEndpoint":[ + "https://example.com/path1" + ] + } + ] +} +``` + +The content of the DID document is explained as follows: + +- `context` is fix defined for the current used schema of DID documents. It depicts the namespace for the W3C DID +- `id` is the DID of the participant +- `verificationMethod` is a list of accepted verification methods +- `authentication` a list of keys to be able to prove that the participant has a specific attribute or controls a specific secret. Used to prove that the participants has the private key associated with public key above +- `service` a list of service endpoints provided by the participants the DID document represents + +### 2.2 DID DOCUMENT LOCATION AND RESOLUTION + +The used DID method for Release 24.05 is -as mentioned- `did:web` which means that the DID itself includes the location to the DID document. +The location of the DID document is accessible over http or https and provided by the Core Service Provider. + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +W3C Decentralized Identifiers [https://www.w3.org/TR/did-core/] +W3C DID Document properties [https://www.w3.org/TR/did-spec-registries/#did-document-properties] +W3C-CCG did:web method [https://w3c-ccg.github.io/did-method-web/] + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +Not applicable. + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +Not applicable. + +### TABLES + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0050-FrameworkAgreementCredential/CX-0050-FrameworkAgreementCredential.md b/docs/standards/CX-0050-FrameworkAgreementCredential/CX-0050-FrameworkAgreementCredential.md new file mode 100644 index 000000000..114bb77bc --- /dev/null +++ b/docs/standards/CX-0050-FrameworkAgreementCredential/CX-0050-FrameworkAgreementCredential.md @@ -0,0 +1,355 @@ +# CX-0050 Framework Agreement Credential v2.0.0 + +## REVISIONS & UPDATE + +- Re-definition of the Framework Agreement structure + +## COPYRIGHT & TRADEMARKS + +## ABSTRACT + +The Framework Agreement Credential is a Verifiable Credential which confirms that a participant has signed a use case specific framework agreement. This document specifies the technical documentation and the structure of the Framework Agreement Credential. + +## 1. INTRODUCTION + +The data exchange between two or multiple companies needs to be legally agreed between them. For some specific use cases a framework agreement which defines the basic rules for data consumption, storage, transfer and re-usage can be agreed on between multiple participants of this specific use case. +Using Decentralized Identifiers for a Self-Sovereign Identity, Verifiable Credentials are used to confirm a participant that he has agreed to the framework agreement and has signed it. + +### 1.1 AUDIENCE & SCOPE + +#### AUDIENCE + +The standard is relevant for the following roles: + +- Core Service Provider as this is the entity being able to issue framework agreement credentials +- Data Provider / Consumer as they exchange these framework agreement credential to prove consent to the framework agreement + +#### SCOPE + +> *This section is non-normative* + +This document covers the specification of the framework agreement credential. It describes + +- the structure of the framework agreement credential +- the content of the framework agreement credential +- the field details of the framework agreement credential +- and the collection of the available and usable framework agreement credentials + +What is **not** in scope is the description or the definition of the agreement itself. + +### 1.2 CONTEXT + +> *This section is non-normative* + +The Framework Agreement Credential is issued by the Core Service Provider to the Wallet of the participant and is exchanged by the Dataspace client in the course of data exchange. It is an attribute of the participants which approves to an other participant that a Framework Agreement for a specific use case is signed. + +A use case Framework Agreement defines the conditions for data exchange in a particular use case. Having signed this framework agreement is approved by a verifiable credential issued to the signing participant. This is done by the core service provider after an appropriate check of the approval of the participant to the framework agreement. The exchange of this credential allows participants to validate each other that they have agreed to the conditions defined in the framework agreement. The data provider can validate that the data consumer has signed the appropriate framework agreement. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +`Core Service Provider` + +All Core Service Providers providing the issuance of Use Case Framework Agreement Credentials must ensure that these credentials follow the structure described in section [2.2 FRAMEWORK AGREEMENT CREDENTIAL STRUCTURE](#22-framework-agreement-credential-structure) and contain the data according to the linked verifiable credentials of the collection in section [section 2.3 Framework Agreement Credential Collection](#23-framework-agreement-credential-collection) and following. + +All Core Service Providers providing the issuance of Use Case Framework Agreement credentials must ensure that the Use Case Framework Agreements have been signed correctly by the participants. + +To validate these criteria of conformance to the Use Case Framework Agreements the following information **MUST** be handed to the Conformity Assessment Body by the Core Service Provider: + +- The validation / control process of the participants signature +- A documentation (e.g. based on Arc42) explaining the architecture, process flows and data structures of the implementation. + +### 1.4 EXAMPLES + +Not applicable. + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +Not applicable. + +## 2. FRAMEWORK AGREEMENT CREDENTIAL + +> *This section is normantive* + +### 2.1 Framework Agreement Credential Content + +The Framework Agreement Credential is a verifiable credential proving that the holder of the credential has signed a framework agreement. +It contains the name of the use case framework agreement, a link to framework agreement document and the version of the use case agreement document. + +### 2.2 Framework Agreement Credential Structure + +The structure of the use case framework agreement credential is as follows: + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "{name}Credential"], + "issuanceDate": "{issuance date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "{did holder}", + "holderIdentifier": "{bpn}", + "group": "UseCaseFramework", + "useCase": "{useCase}", + "contractTemplate": "{URL OF AGREEMENT/CONTRACT TEMPLATE}", + "contractVersion": "{VERSION OF THE AGREEMENT TEMPLATE; format: x.x}" + } +} + +``` + +The content of the Framework Agreement Credential is as follows: + +- `id` is the uuid of the newly created credential - the uuid is defined by the issuer component +- `context` is fix defined for the current used schema - we should already consider that the schema might get updated in future ideally we are flexible to have this scenario that the old schema is set to "INACTIVE" and a new schema is used for new created credentials +- `type` is fix defined for this specific credential +- `issuanceDate` calculated on runtime +- `expirationDate` calculated by the issuer component based on defined credential static data expiry date => always not > 12 month +- `issuer` holds the issuer did +- `credentialSubject` + - `id` holds the customer/holder did + - `holderidentifier` BPN number of the holder + - `group` groupType - fix value "UseCaseFramework" + - `useCase` the linked useCase + - `contractTemplate` contractTemplateDocument of the Framework + - `contractVersion` Framework version - important since you can hold the same credential for multiple versions + +### 2.3 Framework Agreement Credential Collection + +#### 2.3.1 Product Carbon Footprint Framework Agreement Credential (PcfCredential) + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "PcfCredential"], + "issuanceDate": "{issuance date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "{did holder}", + "holderIdentifier": "{bpn}", + "group": "UseCaseFramework", + "useCase": "Pcf", + "contractTemplate": "{URL OF AGREEMENT/CONTRACT TEMPLATE}", + "contractVersion": "{VERSION OF THE AGREEMENT TEMPLATE; format: x.x}" + } +} +``` + +#### 2.3.2 Traceability Framework Agreement Credential (TraceabilityCredential) + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "TraceabilityCredential"], + "issuanceDate": "{issuance date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "{did holder}", + "holderIdentifier": "{bpn}", + "group": "UseCaseFramework", + "useCase": "Traceability", + "contractTemplate": "{URL OF AGREEMENT/CONTRACT TEMPLATE}", + "contractVersion": "{VERSION OF THE AGREEMENT TEMPLATE; format: x.x}" + } +} +``` + +#### 2.3.3 Quality Framework Agreement Credential (QualityCredential) + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "QualityCredential"], + "issuanceDate": "{issuance date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "{did holder}", + "holderIdentifier": "{bpn}", + "group": "UseCaseFramework", + "useCase": "Quality", + "contractTemplate": "{URL OF AGREEMENT/CONTRACT TEMPLATE}", + "contractVersion": "{VERSION OF THE AGREEMENT TEMPLATE; format: x.x}" + } +} +``` + +#### 2.3.4 Circular Economy Framework Agreement Credential (CircularEconomyCredential) + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "CircularEconomyCredential"], + "issuanceDate": "{issuance date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "{did holder}", + "holderIdentifier": "{bpn}", + "group": "UseCaseFramework", + "useCase": "CircularEconomy", + "contractTemplate": "{URL OF AGREEMENT/CONTRACT TEMPLATE}", + "contractVersion": "{VERSION OF THE AGREEMENT TEMPLATE; format: x.x}" + } +} +``` + +#### 2.3.5 Demand and Capacity Framework Agreement Credential (DemandCapacityCredential) + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "DemandCapacityCredential"], + "issuanceDate": "{issuance date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "{did holder}", + "holderIdentifier": "{bpn}", + "group": "UseCaseFramework", + "useCase": "DemandAndCapacity", + "contractTemplate": "{URL OF AGREEMENT/CONTRACT TEMPLATE}", + "contractVersion": "{VERSION OF THE AGREEMENT TEMPLATE; format: x.x}" + } +} +``` + +#### 2.3.6 PURIS Framework Agreement Credential (PurisCredential) + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "PurisCredential"], + "issuanceDate": "{issuance date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "{did holder}", + "holderIdentifier": "{bpn}", + "group": "UseCaseFramework", + "useCase": "DemandAndCapacity", + "contractTemplate": "{URL OF AGREEMENT/CONTRACT TEMPLATE}", + "contractVersion": "{VERSION OF THE AGREEMENT TEMPLATE; format: x.x}" + } +} +``` + +#### 2.3.7 Business Partner Framework Agreement Credential (BusinessPartnerCredential) + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "BusinessPartnerCredential"], + "issuanceDate": "{issuance date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "{did holder}", + "holderIdentifier": "{bpn}", + "group": "UseCaseFramework", + "useCase": "BusinessPartnerDataManagement", + "contractTemplate": "{URL OF AGREEMENT/CONTRACT TEMPLATE}", + "contractVersion": "{VERSION OF THE AGREEMENT TEMPLATE; format: x.x}" + } +} +``` + +#### 2.3.8 Behavioral Twin Framework Agreement Credential (BehavioralTwinCredential) + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "BehavioralTwinCredential"], + "issuanceDate": "{issuance date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "{did holder}", + "holderIdentifier": "{bpn}", + "group": "UseCaseFramework", + "useCase": "BehavioralTwin", + "contractTemplate": "{URL OF AGREEMENT/CONTRACT TEMPLATE}", + "contractVersion": "{VERSION OF THE AGREEMENT TEMPLATE; format: x.x}" + } +} +``` + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +Not applicable. + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +Not applicable. + +### TABLES + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0053-BPNDiscoveryServiceAPIs/CX-0053-BPNDiscoveryServiceAPIs.md b/docs/standards/CX-0053-BPNDiscoveryServiceAPIs/CX-0053-BPNDiscoveryServiceAPIs.md new file mode 100644 index 000000000..eb15b5ae0 --- /dev/null +++ b/docs/standards/CX-0053-BPNDiscoveryServiceAPIs/CX-0053-BPNDiscoveryServiceAPIs.md @@ -0,0 +1,206 @@ +# CX-0053 Discovery Finder and BPN Discovery Service APIs v1.1.0 + +## ABSTRACT + +The EDC discovery service as defined in CX-0001 supports to find EDC endpoints of participants of +the data space via Business Partner Numbers (BPN). In some use cases the BPN needed to access an +EDC data asset is not known. This means that all EDCs in the data space need to be accessed to find + a specific EDC asset under consideration. This broadcasting has very low performance and produces + a high access load to the EDCs. + +BPN discovery services help to restrict the number of EDCs to be accessed. Prerequisite is that the +business application has some other identifying information and a corresponding BPN discovery service +supports the search for the BPN for this kind of identifying information. + +## FOR WHOM IS THE STANDARD DESIGNED + +This standard is designed for data discovery in Catena-X. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +Changes compared to V1.0.1 of CX-0053: + +- added links to openAPI and documentation in Tractus-X instead of specification in document itself +- updated API endpoints and resources +- added reference implementations +- only CX-0010 normative reference, all other normative references now in chapter for non-normative references + +## 1. INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for a + +- Business Application Provider +- Enablement Service Provider +- Core Service Provider + +The standard is relevant for the roles in the following cases: + +- Business Application Provider who does not know the BPN of the data asset under consideration, +but needs to know it, e.g. to discover available EDC connectors +- Enablement Service Provider who wants to provide BPN discovery services +- Core Service Provider who wants to provide the Discovery Finder service + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +#### Context + +The EDC discovery service as defined in CX-0001 supports to find EDC endpoints of participants of +the data space via BPNs, CX-0010. In some use cases the BPN is not known at the start of the process. +This means that all EDCs in the data space need to be accessed to find a specific EDC data asset under consideration. This broadcasting has very low performance and produces a high access load on the EDCs. + +BPN discovery services help to restrict the number of EDCs to be accessed. Prerequisite is that the +business application provider or data consumer has some additional information, +e.g. the Original Equipment Number. + +#### ARCHITECTURE OVERVIEW + +Figure 1 gives a rough overview of the architecture. A Data Consuming Application uses the discovery +services to find the Eclipse Dataspace Connector (EDC), CX-0018, that most probably provides the data +needed. +The starting point for most applications to find data is a corresponding lookup in the Digital Twin +Registry CX-0002. Based on specific asset IDs the Digital Twin Registry enables the lookup of digital +twins and the endpoints to the data they provide. +In this architecture the Digital Twin Registry is decentralized and is accessed via the EDC of the +data provider. This means that the data consuming application needs to know the endpoint of this EDC. +The lookup of EDC endpoints is done via the BPN using the EDC Discovery service CX-0001. +Depending on the context the BPN might not be known for a product under consideration. +In this case BPN Discovery services can be used. Since there might be more than one BPN Discovery Service +a Discovery Finder service enables the lookup of the suitable BPN Discovery services. + +![Discovery_Services_in_the_C-X_Architecture](./assets/discovery-services-in-the-CX-architecture.jpg) + +Figure 1 Discovery Services in the Catena-X Architecture + +### 1.3 Conformance and Proof of Conformity + +> *This section is non-normative* + +#### CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD and SHOULD NOT in this document are to be interpreted as described in \[[BCP 14](https://datatracker.ietf.org/doc/html/bcp14)], \[[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)\], \[[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)\] when, and only when, they appear in all capitals, as shown here. + +#### PROOF OF CONFORMITY + +All participants and their solutions will need to proof, that they are conform +with the Catena-X standards. To validate that the standards are applied +correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +The central operating company MUST provide the central Discovery Finder service conformant to the API specified in this standard. + +Any operating company MAY provide BPN Discovery services conformant to the API specified in this standard. + +The central operating company MUST ensure that there is at least one BPN Discovery service provided +per demand of a KIT. The BPN Discovery API as specified in the standard is generic. Which keys MUST +be supported is specified in the corresponding use case specific standards. + +### 1.4 EXAMPLES + +For examples see the different payload examples in the documentation of the API normative parts. + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +Business Partner Number (BPN) + +> A BPN is the unique identifier of a partner within Catena-x. + +Additional terminology used in this standard can be looked up in the glossary on +the association homepage. + +## 2. DISCOVERY FINDER API + +> *This section is normative* + +## 2.1 PRECONDITIONS AND DEPENDENCIES + +This service is a prerequisite to find the available BPN Discovery Services. + +## 2.2 API SPECIFICATION + +### 2.2.1 API Endpoints & resources + +The API endpoints MUST be implemented conformant to the [openAPI specification]( +https://github.com/eclipse-tractusx/sldt-discovery-finder/blob/main/backend/src/main/resources/static/discovery-finder-openapi.yaml) for the discovery finder service. + +For further information on the discovery finder service see its [documentation]( https://github.com/eclipse-tractusx/sldt-discovery-finder/blob/main/docs/documentation.md). + +### 2.2.2 Available Data Types + +The API MUST use JSON as the payload transported via HTTP. + +### 2.2.3 EDC Data Asset Structure + +As the services specified by this standard run without shielding by an EDC, definition of a Data Asset Structure is obsolete. + +### 2.2.4 Error Handling + +See API Endpoints & resources for the http response codes that MUST be defined for HTTP POST endpoints. + +## 3. BPN DISCOVERY API + +> *This section is normative* + +### 3.1 PRECONDITIONS AND DEPENDENCIES + +A Discovery Finder service is a prerequisite to find the available BPN Discovery Services. + +### 3.2 API SPECIFICATION + +#### 3.2.1 API Endpoints & Resources + +The API endpoints MUST be implemented conformant to the the [openAPI specification]( +https://github.com/eclipse-tractusx/sldt-bpn-discovery/blob/main/backend/src/main/resources/static/bpn-discovery-service-openapi.yaml) for the BPN discovery service. + +For further information on the service see its [documentation]( https://github.com/eclipse-tractusx/sldt-bpn-discovery/blob/main/docs/documentation.md). + +#### 3.2.2 Available Data Types + +The API MUST use JSON as the payload transported via HTTP. + +#### 3.2.3 Error Handling + +See API Endpoints & resources for the http response codes that MUST be defined for HTTP POST endpoints. + +## 4. REFERENCES + +### 4.1 NORMATIVE REFERENCES + +CX-0010 Business Partner Number (BPN) + +### 4.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +CX-0001 EDC Discovery API + +CX-0002 Digital Twins in Catena-X + +CX-0012 Business Partner Data Pool + +CX-0018 Eclipse Data Space Connector + +[Catena-X Operating Model Whitepaper](https://catena-x.net/fileadmin/user_upload/Publikationen_und_WhitePaper_des_Vereins/CX_Operating_Modelv2.1_final.pdf). Whitepaper. Release V2.1 – October 16, 2023. Catena-X e.V. + +### 4.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +This is a reference implementation for the Discovery Finder Service: +https://github.com/eclipse-tractusx/sldt-discovery-finder + +This is a reference implementation for the BPN Discovery Service: +https://github.com/eclipse-tractusx/sldt-bpn-discovery + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0053-BPNDiscoveryServiceAPIs/assets/discovery-services-in-the-CX-architecture.jpg b/docs/standards/CX-0053-BPNDiscoveryServiceAPIs/assets/discovery-services-in-the-CX-architecture.jpg new file mode 100644 index 000000000..d79cb5cea Binary files /dev/null and b/docs/standards/CX-0053-BPNDiscoveryServiceAPIs/assets/discovery-services-in-the-CX-architecture.jpg differ diff --git a/docs/standards/CX-0054-ApplicationServiceRelease/CX-0054-ApplicationServiceRelease.md b/docs/standards/CX-0054-ApplicationServiceRelease/CX-0054-ApplicationServiceRelease.md new file mode 100644 index 000000000..d0fabdbfd --- /dev/null +++ b/docs/standards/CX-0054-ApplicationServiceRelease/CX-0054-ApplicationServiceRelease.md @@ -0,0 +1,369 @@ +# CX-0054 Application Service Release v1.0.1 + +## ABSTRACT + +> *This section is non-normative* + +This document defines the release process for applications and services within the Catena-X marketplaces. + It provides guidance and requirements for participants who develop, deploy, and maintain applications + and services. The document covers the release process for both new and updated applications +and services, including versioning, testing, and deployment procedures. It also includes information +on the conformance criteria and proof of conformity requirements. This document is intended for participants +in the Catena-X network who are involved in the development, deployment, and +maintenance of applications and services. It is also relevant for organizations that provide tools and +services that support the Catena-X network. + +## 1. INTRODUCTION + +> *This section is non-normative* + +Catena-X Marketplace is a digital platform that aims to connect businesses with Catena-X certified + applications and services and provide a seamless exchange of data and services. To ensure the + platform's quality and stability, it's crucial to have a well-defined and documented process for + releasing applications and services onto the platform. + +This document specifies the Application and Service Release Process for a Catena-X Marketplace. + It outlines the steps and requirements that must be followed by service providers and application + developers when submitting new or updated applications or services to the marketplace. + +The scope of this document is limited to the Application and Service Release Process and does not + cover other aspects of the Catena-X Marketplace, such as user management, security, or data exchange + protocols. An example service, namely "Auto-Setup", and its release and deployment process can be found + under [3.3 REFERENCE IMPLEMENTATIONS](#33-reference-implementations). + +This document is intended for core service providers, business application providers, and any other stakeholders + involved in the release of applications and services on the Catena-X Marketplace. It provides guidance + on the required steps and best practices for ensuring the quality and reliability of the Catena-X + marketplaces with preparation of enabling the coexistence of multiple federated marketplaces + of Catena-X by following Catena-X standards. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +The following roles are relevant to the Application and Service Release Process specification for + the Catena-X Marketplace: + +**Core Service Provider**: The Core Service Provider is responsible for developing and maintaining + the core services and components of the Catena-X Marketplace. This includes defining the release + process and requirements for application and service releases. + +**Business Application Provider**: The Business Application Provider is responsible for developing + and maintaining the applications and services that run on top of the core services of the Catena-X + Marketplace. This includes following the release process and requirements defined by the Core + Service Provider. + +**Enablement Service Provider**: The Enablement Service Provider is responsible for providing services + that enable the integration of external systems with the Catena-X Marketplace. This includes following + the release process and requirements defined by the Core Service Provider when releasing their services. + +### 1.2 CONTEXT + +> *This section is non-normative* + +The Application and Service Release Process APIs are key components of the Catena-X Marketplace, + enabling core service providers, business application providers and enablement service providers + to release new or updated services onto the marketplace. These APIs allows for the submission of + new application and service offerings, updates to existing applications or services, and management + of application or service subscriptions. The Service Release Process API is built + on the `Org.Eclipse.TractusX.Portal.Backend.Services.Service` v2 specification and is accessible + via the `/api/services/ServiceRelease` endpoints. The Application Release Process API is built on + `Org.Eclipse.TractusX.Portal.Backend.Apps.Service` v2 specification and is + accessible via the `/api/apps/AppReleaseProcess` endpoints. + +Through these APIs, providers can perform a range of actions, such as retrieving agreement data, + retrieving details on services or apps in review, and managing status updates. Providers can also + add, subscribe to, and update apps or services, as well as manage agreements and consent statuses. + Additionally, providers can retrieve information on active applications in the marketplace, view + subscription details, and auto-setup services. + +The Application and Service Release Process APIs are essential for enabling a smooth and efficient + process for managing service and application releases and updates in the Catena-X Marketplace. Its + comprehensive set of endpoints allows providers to easily manage their offerings and subscriptions + while ensuring compliance with authorization requirements and role-based access controls. + +### 1.3 ARCHITECTURE OVERVIEW + +> *This section is non-normative* + +#### 1.3.1 OVERVIEW OF RELEASE PROCESS API + +> **Note** : As Application Release Process API (found under: `/api/apps/AppReleaseProcess/`) +> is more detailed than and is a superset of the Service Release Process API (found under: +> `/api/services/servicerelease/`) only Application Release Process API is described in this chapter. + +The portal backend service provides a list of API endpoints that can be accessed with +various HTTP methods such as GET, POST, PUT, and DELETE. The APIs are categorized under +three different titles, which are Apps, AppReleaseProcess, and AppChange. + +The AppReleaseProcess category contains APIs related to app management and release +processes. For instance, the `/api/apps/AppReleaseProcess/createapp` endpoint creates +an app according to the provided request model, and the +`/api/apps/AppReleaseProcess/updateapp/{appId}` endpoint updates the details of a +newly created owned app under the app release/publishing process. Some other endpoints +such as `/api/apps/AppReleaseProcess/{appId}/appStatus` and +`/api/apps/AppReleaseProcess/{appId}/approveApp` provide additional functionality such +as retrieving the app detail with status and approving the app to change the status from +IN_REVIEW to Active and create notification. + +The Apps category includes APIs that allow Catena-X dataspace participants to access and retrieve information +related to apps. For instance, the `/api/Apps/active` endpoint retrieves all active apps +in the marketplace, and the `/api/Apps/{appId}` endpoint retrieves app details for an app +referenced by ID. The `/api/Apps/favourites` endpoint retrieves the IDs of all favorite +apps of the current user, while the `/api/Apps/{appId}/subscribe` endpoint adds an app +to the current user's company's subscriptions. + +Each API endpoint requires authorization and access permission to be accessed. The +permission level required for each API is specified in the description of the respective +API endpoint. The authorization requirement ranges from view_apps to edit_apps and add_apps. + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, +examples, and notes in this specification are non-normative. Everything else in +this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, +**REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be +interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they +appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to prove that they conform +with the Catena-X standards. To validate that the standards are applied +correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To prove conformity with the Application and Service Release Process standard, + you MUST provide the following assets to a conformity assessment body: + +**For Application Release Process:** + +- *Release process documentation* of the marketplace implementation that is to be certified SHOULD + match to the Application Release Process documentation and workflows +- *Documentation of API responses* of the marketplace implementation that is to be certified + SHOULD match to the Application Release Process API responses listed under + [2.1.1 APPLICATION RELEASE PROCESS API](#211-application-release-process-api) + +**For Service Release Process:** + +- *Release process documentation* of the marketplace implementation that is to be certified SHOULD + match to the Service Release Process Documentation and workflows +- *Documentation of API responses* of the marketplace implementation that is to be certified + SHOULD match to the Service Release Process API responses listed under + [2.2.1 SERVICE RELEASE PROCESS API](#221-service-release-process-api) + +### 1.6 EXAMPLES + +Examples and further information can be found in the + [Tractus-X Github Repository > Portal > Application Release Process](https://github.com/eclipse-tractusx/portal-assets/tree/main/docs/04.%20App(s)/02.%20App%20Release%20Process) + and in the [Tractus-X Github Repository > Portal > Service Release Process](https://github.com/eclipse-tractusx/portal-assets/tree/main/docs/05.%20Service(s)/02.%20Service%20Release%20Process) + and in the [Tractus-X Github Repository > Auto-Setup Backend > Documentation](https://github.com/eclipse-tractusx/autosetup-backend/blob/main/docs/ARC42.md) + +### 1.7 TERMINOLOGY + +> *This section is non-normative* + +Catena-X Marketplace +: A Marketplace in Catena-X Core Services context is a digital platform where businesses can provide, + list and find applications and services that are certified to be used in Catena-X network and ecosystem + +Additional terminology used in this standard can be looked up in the glossary on +the association homepage. + +## 2 APPLICATION AND SERVICE RELEASE PROCESS + +> *This section is normative* + +The Application and Service Release Process standardization should act as an enabler for + interoperability between different Catena-X application or service marketplace offerings. + +### 2.1 APPLICATION RELEASE PROCESS + +If a Catena-X Marketplace which is listing Catena-X Applications is to be certified, it: + +- MUST provide public access to the documentation of its own Application Release Process +- MUST provide API access to Application Release Process Workflow and public access to the API documentation +- MUST fulfill the service and app release process standards defined by the Catena-X association \{reference to the respective chapters useful\} + +A Catena-X Marketplace Application Release Process: + +- MUST enable app provider to request the release of their business application under their company name +- MUST enable app provider to access and agree to the terms and conditions of the CX marketplace per app release request +- MUST enable app provider to upload their app roles which enables on a later state the SSO connection between the portal and the provider app +- MUST collect all defined app attributes as per the list below + - app name + - linked use case + - supported language + - pricing + - lead image + - long description (en & de) + - App Data Privacy/Collection Information + - App Conformity Certificate + - App Roles +- SHOULD collect all defined app attributes as per the list below + - short description (en & de) + - sales manager (optional) + - detail images (minimum one) + - Data Pre-requisits (pdf) - optional + - Technical Guide (pdf) - optional + - App Contract (pdf) - optional + - Provider Details - optional (Homepage, Contact, Number) +- SHOULD provide a GUI and an API to allow application publishers to publish following information in particular, but not limited to: +see all attributes mentioned above +- MUST enable the app provider to store the app data in a draft state and submit the app for the marketplace publishing later +- MUST implement a process to validate the app publishing request before approving and publishing the app on the marketplace +- SHOULD implement a process to decline/cancel an app publishing request +- MUST store the documents (incl. the conformity certificate) +- SHOULD enable the app provider to deactivate an app from the marketplace +- SHOULD enable the app provider to change the app details (such as description, documents, roles etc.) + +### 2.1.1 APPLICATION RELEASE PROCESS API + +If a Catena-X Marketplace which is listing Catena-X Applications is to be certified, + it MUST implement and give access to following API endpoints: + +| Endpoint | Description | Authorization Required | Roles | +| --- | --- | --- | --- | +| `GET: /api/apps/active` | Retrieves all active apps in the marketplace. | Yes | `view_apps` | +| `GET: /api/apps/business` | Retrieves all apps that the currently logged in user has been assigned roles in. | Yes | `view_apps` | +| `GET: /api/apps/{appId}` | Retrieves app details for an app referenced by ID. | Yes | `view_apps` | +| `GET: /api/apps/subscribed/subscription-status` | Retrieves subscription statuses of subscribed apps of the currently logged in user's company. | Yes | `view_subscription` | +| `GET: /api/apps/provided/subscription-status` | Retrieves subscription statuses of provided apps of the currently logged in user's company. | Yes | `view_app_subscription` | +| `POST: /api/apps/{appId}/subscribe` | Adds an app to the current user's company's subscriptions. | Yes | `subscribe_apps` | +| `GET: /api/apps/appAgreementData/{appId}` | Gets all agreements. | Yes | `subscribe_apps` | +| `GET: /api/apps/provided` | Retrieves all company-owned apps. | Yes | `app_management` | +| `POST: /api/apps/autoSetup` | Auto setup the app *obsolete* . | Yes | `activate_subscription` | +| `POST: /api/Apps/start-autoSetup` | Auto setup the app per process worker. | Yes | `activate_subscription` | +| `POST: /api/apps/appreleaseprocess/{appId}/role` | Creates a new role for a given app. | Yes | `edit_roles` | +| `GET: /api/apps/appreleaseprocess/agreementData` | Retrieves app agreement data. | Yes | `view_apps` | +| `GET: /api/apps/appreleaseprocess/consent/{appId}` | Retrieves consent data for a given app. | Yes | `view_apps` | +| `POST: /api/apps/appreleaseprocess/consent/{appId}/agreementConsents` | Creates a new consent agreement for a given app. | Yes | `edit_apps` | +| `GET: /api/apps/appreleaseprocess/{appId}/appStatus` | Retrieves status information for a given app. | Yes | `view_apps` | +| `DELETE: /api/apps/appreleaseprocess/{appId}/role/{roleId}` | Deletes a given role for a given app. | Yes | `edit_roles` | +| `POST: /api/apps/appreleaseprocess/createapp` | Creates a new app. | Yes | `add_apps` | +| `PUT: /api/apps/appreleaseprocess/{appId}` | Updates an existing app. | Yes | `edit_apps` | +| `PUT: /api/apps/appreleaseprocess/{appId}/submit` | Submits an app for release. | Yes | `edit_apps` | +| `PUT: /api/apps/appreleaseprocess/{appId}/approveApp` | Approves a pending app release. | Yes | `approve_apps` | +| `PUT: /api/apps/appreleaseprocess/{appId}/declineApp` | Declines a pending app release. | Yes | `approve_apps` | +| `GET: /api/apps/appreleaseprocess/privacyPolicies` | Retrieves privacy policy data. | Yes | `view_apps` | + +### 2.2 SERVICE RELEASE PROCESS + +If a Catena-X Marketplace which is listing Catena-X Services is to be certified, + +- MUST provide public access to the documentation of its own Application Release Process +- MUST provide API access to Application Release Process Workflow and public access to the API documentation +- MUST fulfill the service and app release process standards defined by the Catena-X association \{reference to the respective chapters useful\} + +A Catena-X Marketplace Service Release Process: + +- MUST enable service provider to request the release of their service under their company name +- MUST enable service provider to access and agree to the terms and conditions of the CX marketplace per service release request +- MUST collect all defined service attributes as per the list below + - service name + - short description (en & de) + - pricing + - long description (en & de) +- SHOULD collect all defined app attributes as per the list below + - lead image + - sales manager - optional + - Supporting Material (pdf) - optional + - Provider Details - optional (Homepage, Contact, Number) +- SHOULD provide a GUI and an API to allow service publishers to publish following information in particular, but not limited to: +see all attributes mentioned above +- MUST enable the service provider to store the service data in a draft state and submit the serice for the marketplace publishing later +- MUST implement a process to validate the service publishing request before approving and publishing the app on the marketplace +- SHOULD implement a process to decline/cancel an service publishing request +- SHOULD enable the service provider to deactivate an service from the marketplace +- SHOULD enable the service provider to change the service details (such as description, documents, etc.) + +### 2.2.1 SERVICE RELEASE PROCESS API + +If a Catena-X Marketplace which is listing Catena-X Services is to be certified, + it MUST implement and give access to following API endpoints: + +| Endpoint | Description | Authorization Required | Roles | +| --- | --- | --- | --- | +| `GET: /api/Services/active` | Retrieves all active services in the marketplace. | Yes | `view_service_offering` | +| `GET: /api/Services/{serviceId}` | Retrieves service offer details for the respective service id. | Yes | `view_service_offering` | +| `PUT: /api/services/{serviceId}` | Updates the service inside the service release process. | Yes | `update_service_offering` | +| `POST: /api/Services/{serviceId}/subscribe` | Adds a new service subscription. | Yes | `subscribe_service` | +| `PUT: /api/Services/{serviceId}/submit` | Submit an Service for release. | Yes | `add_service_offering` | +| `PUT: /api/Services/{serviceId}/approveService` | Approve Service to change status from IN_REVIEW to Active and create notification. | Yes | `approve_service_release` | +| `PUT: /api/Services/{serviceId}/declineService` | Declines the service request. | Yes | `decline_service_release` | +| `GET: /api/Services/provided` | Retrieves all in review status service in the marketplace. | Yes | `add_service_offering` | +| `POST: /api/Services/autoSetup` | Auto setup the service. | Yes | `activate_subscription` | +| `GET: /api/Services/provided/subscription-status` | Retrieves subscription statuses of provided services of the currently logged in user's company. | Yes | `view_service_subscriptions` | +| `GET: /api/Services/serviceAgreementData/{serviceId}` | Gets all agreements. | Yes | `subscribe_service_offering` | +| `GET: /api/services/ServiceRelease/agreementData` | Return Agreement Data for offer_type_id Service. | Yes | `add_service_offering` | +| `GET: /api/services/ServiceRelease/{serviceId}/serviceStatus` | Return app detail with status. | Yes | `add_service_offering` | +| `GET: /api/services/ServiceRelease/inReview` | Retrieves all in review status service in the marketplace. | Yes | `approve_service_release`, `decline_service_release` | +| `GET: /api/services/ServiceRelease/inReview/{serviceId}` | Retrieves service details for an offer referenced by id. | Yes | `approve_service_release`, `decline_service_release` | +| `GET: /api/services/ServiceRelease/serviceTypes` | Retrieve Service Type Data. | Yes | `add_service_offering` | +| `GET: /api/services/ServiceRelease/consent/{serviceId}` | Gets the agreement consent status for the given service id. | Yes | `add_service_offering` | +| `POST: /api/services/ServiceRelease/consent/{serviceId}/agreementConsents` | Update or Insert Consent. | Yes | `add_service_offering` | + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- CX-0006 REGISTRATION AND INITIAL ONBOARDING +- CX-0009 CATENA-X REGISTRATION API +- CX-0010 BUSINESS PARTNER NUMBER (BPN) +- CX-0011 ISSUING AGENCY +- CX-0013 IDENTITY OF MEMBER COMPANIES + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +The code found at following locations present reference implementations that implement this standard: + +- [Catena-X Portal Frontend](https://github.com/eclipse-tractusx/portal-frontend) +- [Catena-X Portal Backend](https://github.com/eclipse-tractusx/portal-backend) +- [Catena-X Portal Assets](https://github.com/eclipse-tractusx/portal-assets) +- [Helm chart for Catena-X Portal](https://github.com/eclipse-tractusx/portal-cd) + +The code found at following location presents a reference implementation that implements a service that uses a service release process: + +- [Auto Setup Service](https://github.com/eclipse-tractusx/autosetup-backend) + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +The image found below depicts an example Application Release Process that implements this standard. + +![Application Release Process](./assets/215894184-38a86c3e-4583-4b7f-ac9a-86b6f3e0f82b.png) + +The image found below depicts an example Application Creation Page that implements this standard. + +![Application Creation Page](./assets/211015263-2fc2adf5-df18-4559-9f6f-c2e90e7f8495.png) + +The image found below depicts an example Application Detail Input Page that implements this standard. + +![Application Detail Page](./assets/215898791-b832d31c-8c37-4483-af45-53b263c649c4.png) + +The image found below depicts an example Service Detail Input Page that implements this standard. + +![Service Detail Page](./assets/229457934-9748b493-eaf6-4bf7-b2f6-bf7ea6d352c5.png) + +### TABLES + +> *This section is non-normative* + +The json api description found in [openpi json file](./assets/swagger.json) presents a reference API + that implements this standard. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0054-ApplicationServiceRelease/assets/211015263-2fc2adf5-df18-4559-9f6f-c2e90e7f8495.png b/docs/standards/CX-0054-ApplicationServiceRelease/assets/211015263-2fc2adf5-df18-4559-9f6f-c2e90e7f8495.png new file mode 100644 index 000000000..427a76418 Binary files /dev/null and b/docs/standards/CX-0054-ApplicationServiceRelease/assets/211015263-2fc2adf5-df18-4559-9f6f-c2e90e7f8495.png differ diff --git a/docs/standards/CX-0054-ApplicationServiceRelease/assets/215894184-38a86c3e-4583-4b7f-ac9a-86b6f3e0f82b.png b/docs/standards/CX-0054-ApplicationServiceRelease/assets/215894184-38a86c3e-4583-4b7f-ac9a-86b6f3e0f82b.png new file mode 100644 index 000000000..ab59a97eb Binary files /dev/null and b/docs/standards/CX-0054-ApplicationServiceRelease/assets/215894184-38a86c3e-4583-4b7f-ac9a-86b6f3e0f82b.png differ diff --git a/docs/standards/CX-0054-ApplicationServiceRelease/assets/215898791-b832d31c-8c37-4483-af45-53b263c649c4.png b/docs/standards/CX-0054-ApplicationServiceRelease/assets/215898791-b832d31c-8c37-4483-af45-53b263c649c4.png new file mode 100644 index 000000000..de5a4ad3e Binary files /dev/null and b/docs/standards/CX-0054-ApplicationServiceRelease/assets/215898791-b832d31c-8c37-4483-af45-53b263c649c4.png differ diff --git a/docs/standards/CX-0054-ApplicationServiceRelease/assets/229457934-9748b493-eaf6-4bf7-b2f6-bf7ea6d352c5.png b/docs/standards/CX-0054-ApplicationServiceRelease/assets/229457934-9748b493-eaf6-4bf7-b2f6-bf7ea6d352c5.png new file mode 100644 index 000000000..c548b5f4d Binary files /dev/null and b/docs/standards/CX-0054-ApplicationServiceRelease/assets/229457934-9748b493-eaf6-4bf7-b2f6-bf7ea6d352c5.png differ diff --git a/docs/standards/CX-0054-ApplicationServiceRelease/assets/swagger.json b/docs/standards/CX-0054-ApplicationServiceRelease/assets/swagger.json new file mode 100644 index 000000000..744aa14de --- /dev/null +++ b/docs/standards/CX-0054-ApplicationServiceRelease/assets/swagger.json @@ -0,0 +1,3914 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "Org.Eclipse.TractusX.Portal.Backend.Apps.Service", + "version": "v2" + }, + "paths": { + "/api/apps/AppChange/{appId}/role/activeapp": { + "post": { + "tags": [ + "AppChange" + ], + "summary": "dd role and role description for Active App (Authorization required - Roles: edit_apps)", + "description": "Example: POST: /api/apps/appchange/{appId}/role/activeapp", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AppUserRole" + } + } + } + } + }, + "responses": { + "200": { + "description": "created role and role description successfully.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AppRoleData" + } + } + } + } + }, + "400": { + "description": "If sub claim is empty/invalid or user does not exist, or any other parameters are invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "App does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "User not associated with provider company.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "App provider company not set.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/updateapp/{appId}": { + "put": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Add app details to a newly created owned app under the app release/publishing process. (Authorization required - Roles: app_management)", + "description": "Example: PUT: /api/apps/appreleaseprocess/updateapp/74BA5AEF-1CC7-495F-ABAA-CF87840FA6E2", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppEditableDetail" + } + } + } + }, + "responses": { + "204": { + "description": "App was successfully updated." + }, + "400": { + "description": "If sub claim is empty/invalid or user does not exist, or any other parameters are invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "App does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "User does not have edit permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "App is in incorrect state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/updateappdoc/{appId}/documentType/{documentTypeId}/documents": { + "put": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Upload document for active apps in the marketplace for given appId for same company as user (Authorization required - Roles: app_management)", + "description": "Example: PUT: /api/apps/appreleaseprocess/updateappdoc/{appId}/documentType/{documentTypeId}/documents", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "documentTypeId", + "in": "path", + "description": "", + "required": true, + "schema": { + "$ref": "#/components/schemas/DocumentTypeId" + } + } + ], + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "document": { + "type": "string", + "format": "binary" + } + } + }, + "encoding": { + "ContentType": { + "style": "form" + }, + "ContentDisposition": { + "style": "form" + }, + "Headers": { + "style": "form" + }, + "Length": { + "style": "form" + }, + "Name": { + "style": "form" + }, + "FileName": { + "style": "form" + } + } + }, + "application/json": { + "schema": { + "type": "object", + "properties": { + "document": { + "type": "string", + "format": "binary" + } + } + }, + "encoding": { + "ContentType": { + "style": "form" + }, + "ContentDisposition": { + "style": "form" + }, + "Headers": { + "style": "form" + }, + "Length": { + "style": "form" + }, + "Name": { + "style": "form" + }, + "FileName": { + "style": "form" + } + } + } + } + }, + "responses": { + "204": { + "description": "Successfully uploaded the document", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NoContentResult" + } + } + } + }, + "400": { + "description": "If sub claim is empty/invalid or user does not exist, or any other parameters are invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "App does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "The user is not assigned with the app.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Offer is in incorrect state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "415": { + "description": "Only PDF files are supported.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/{appId}/role": { + "post": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Add role and role description for App (Authorization required - Roles: edit_apps)", + "description": "Example: POST: /api/apps/appreleaseprocess/{appId}/role", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AppUserRole" + } + } + } + } + }, + "responses": { + "200": { + "description": "created role and role description successfully.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AppRoleData" + } + } + } + } + }, + "400": { + "description": "If sub claim is empty/invalid or user does not exist, or any other parameters are invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "App does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "User not associated with provider company", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/agreementData": { + "get": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Return Agreement Data for offer_type_id App (Authorization required - Roles: edit_apps)", + "description": "Example: GET: /api/apps/appreleaseprocess/agreementData", + "responses": { + "200": { + "description": "Returns the Cpllection of agreement data", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgreementDocumentData" + } + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/consent/{appId}": { + "get": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Gets the agreement consent status for the given app id (Authorization required - Roles: edit_apps)", + "description": "Example: GET: /api/apps/appreleaseprocess/consent/{appId}", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Returns the Offer Agreement Consent data", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OfferAgreementConsent" + } + } + } + }, + "404": { + "description": "App does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "User not associated with offer.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/consent/{appId}/agreementConsents": { + "post": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Update or Insert Consent (Authorization required - Roles: edit_apps)", + "description": "Example: POST: /api/apps/appreleaseprocess/consent/{appId}/agreementConsents", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OfferAgreementConsent" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully submitted consent to agreements", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ConsentStatusData" + } + } + } + } + }, + "404": { + "description": "App does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Either the user was not found or the user is not assignable to the given application.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "App Id is incorrect.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/{appId}/appStatus": { + "get": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Return app detail with status (Authorization required - Roles: app_management)", + "description": "Example: GET: /api/apps/appreleaseprocess/{appId}/appStatus", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Return the Offer and status data", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppProviderResponse" + } + } + } + }, + "404": { + "description": "App does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "User not associated with provider company.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/{appId}/role/{roleId}": { + "delete": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Removes a role from persistence layer by appId and roleId. (Authorization required - Roles: edit_apps)", + "description": "Example: DELETE: /api/apps/appreleaseprocess/{appId}/role/{roleId}", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "ID of the app to be deleted.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "5636F9B9-C3DE-4BA5-8027-00D17A2FECFB" + }, + { + "name": "roleId", + "in": "path", + "description": "ID of the role to be deleted.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "5636F9B9-C3DE-4BA5-8027-00D17A2FECFB" + } + ], + "responses": { + "204": { + "description": "Empty response on success.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IActionResult" + } + } + } + }, + "404": { + "description": "Record not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Input is incorrect", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "User is not associated with provider company", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/ownCompany/salesManager": { + "get": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Get All Users with Role of Sales Manager (Authorization required - Roles: add_apps)", + "description": "Example: GET: /api/apps/appreleaseprocess/ownCompany/salesManager", + "responses": { + "200": { + "description": "Return the Users with Role of Sales Manager.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CompanyUserNameData" + } + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/createapp": { + "post": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Creates an app according to request model (Authorization required - Roles: add_apps)", + "description": "Example: POST: /api/apps/appreleaseprocess/createapp", + "requestBody": { + "description": "Request model for app creation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppRequestModel" + } + } + } + }, + "responses": { + "201": { + "description": "Returns created app's ID.", + "content": { + "application/json": { + "schema": { + "type": "string", + "format": "uuid" + } + } + } + }, + "400": { + "description": "Language Code or Use Case or CompanyId is incorrect", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "User is not associated with provider company.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/{appId}": { + "put": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Updates an app according to request model (Authorization required - Roles: edit_apps)", + "description": "Example: PUT: /api/apps/appreleaseprocess/15507472-dfdc-4885-b165-8d4a8970a3e2", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "Id of the app to update", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "15507472-dfdc-4885-b165-8d4a8970a3e2" + } + ], + "requestBody": { + "description": "Request model for app creation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppRequestModel" + } + } + } + }, + "responses": { + "204": { + "description": "No Content" + }, + "400": { + "description": "Language Code or Use Case or CompanyId is incorrect", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "App does not exist", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "User don't have permission to change the app.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Offer is in inCorrect State.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "201": { + "description": "Returns created app's ID." + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + }, + "delete": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Delete App by Id (Authorization required - Roles: edit_apps)", + "description": "Example: DELETE: /api/apps/appreleaseprocess/{appId}", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "ID of the app to be deleted.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "5636F9B9-C3DE-4BA5-8027-00D17A2FECFB" + } + ], + "responses": { + "204": { + "description": "Empty response on success.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IActionResult" + } + } + } + }, + "400": { + "description": "Input is incorrect.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "User is not associated with provider company.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "Record not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/inReview": { + "get": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Retrieves all in review status apps in the marketplace . (Authorization required - Roles: approve_app_release,decline_app_release)", + "description": "Example: GET: /api/apps/appreleaseprocess/inReview", + "parameters": [ + { + "name": "page", + "in": "query", + "description": "page index start from 0", + "schema": { + "type": "integer", + "format": "int32", + "default": 0 + } + }, + { + "name": "size", + "in": "query", + "description": "size to get number of records", + "schema": { + "type": "integer", + "format": "int32", + "default": 15 + } + }, + { + "name": "sorting", + "in": "query", + "description": "sort by", + "schema": { + "$ref": "#/components/schemas/OfferSorting" + } + }, + { + "name": "offerStatusIdFilter", + "in": "query", + "description": "Filter by offerStatusId", + "schema": { + "$ref": "#/components/schemas/OfferStatusIdFilter" + } + } + ], + "responses": { + "200": { + "description": "Returns the list of all in review status marketplace apps.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InReviewAppDataResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/{appId}/submit": { + "put": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Submit an app for release (Authorization required - Roles: add_apps)", + "description": "Example: PUT: /api/apps/appreleaseprocess/D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645/submit", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "ID of the app.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645" + } + ], + "responses": { + "204": { + "description": "The app was successfully submitted for release." + }, + "400": { + "description": "Either the sub claim is empty/invalid, user does not exist or the subscription might not have the correct status or the companyID is incorrect.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "App does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "User not associated with company", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/{appId}/approveApp": { + "put": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Approve App to change status from IN_REVIEW to Active and create notification (Authorization required - Roles: approve_app_release)", + "description": "Example: PUT: /api/apps/appreleaseprocess/D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645/approveApp", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "The app was successfully submitted to Active State." + }, + "404": { + "description": "App does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "App is in InCorrect Status", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/privacyPolicies": { + "get": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Retrieve Privacy Policies (Authorization required - Roles: add_apps)", + "description": "Example: GET: /api/apps/appreleaseprocess/privacyPolicies", + "responses": { + "200": { + "description": "Return the privacy policies", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PrivacyPolicyData" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/{appId}/declineApp": { + "put": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Declines the app request (Authorization required - Roles: decline_app_release)", + "description": "Example: PUT: /api/apps/appreleaseprocess/D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645/declineApp", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "Id of the app that should be declined", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645" + } + ], + "requestBody": { + "description": "the data of the decline request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OfferDeclineRequest" + } + } + } + }, + "responses": { + "204": { + "description": "NoContent." + }, + "400": { + "description": "If sub claim is empty/invalid or user does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "If app does not exists.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "User does not have permission to change the app", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Offer is in incorrect state", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/inReview/{appId}": { + "get": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Gets InReview app details for an app referenced by id. (Authorization required - Roles: approve_app_release,decline_app_release)", + "description": "Example: GET: /api/apps/appreleaseprocess/inReview/D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "ID of the app to retrieve.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645" + } + ], + "responses": { + "200": { + "description": "Returns the requested app details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InReviewAppDetails" + } + } + } + }, + "400": { + "description": "If sub claim is empty/invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "App not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/apps/AppReleaseProcess/documents/{documentId}": { + "delete": { + "tags": [ + "AppReleaseProcess" + ], + "summary": "Delete Document Assigned to Offer (Authorization required - Roles: edit_apps)", + "description": "Example: DELETE: /api/apps/appreleaseprocess/documents/{documentId}", + "parameters": [ + { + "name": "documentId", + "in": "path", + "description": "ID of the document to be deleted.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Empty response on success.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IActionResult" + } + } + } + }, + "404": { + "description": "Record not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "User is not allowed to delete the document", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Document or App is in InCorrect Status", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "parameters are invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/active": { + "get": { + "tags": [ + "Apps" + ], + "summary": "Retrieves all active apps in the marketplace. (Authorization required - Roles: view_apps)", + "description": "Example: GET: /api/apps/active", + "parameters": [ + { + "name": "lang", + "in": "query", + "description": "Optional two character language specifier for the app description. Will be empty if not provided.", + "schema": { + "type": "string" + }, + "example": "en" + } + ], + "responses": { + "200": { + "description": "Returns the list of all active marketplace apps.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AppData" + } + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/business": { + "get": { + "tags": [ + "Apps" + ], + "summary": "Get all apps that currently logged in user has been assigned roles in. (Authorization required - Roles: view_apps)", + "description": "Example: GET: /api/apps/business", + "responses": { + "200": { + "description": "Returns the list of the user's business apps.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BusinessAppData" + } + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/{appId}": { + "get": { + "tags": [ + "Apps" + ], + "summary": "Retrieves app details for an app referenced by id. (Authorization required - Roles: view_apps)", + "description": "Example: GET: /api/apps/D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645", + "operationId": "GetAppDetailsByIdAsync", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "ID of the app to retrieve.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645" + }, + { + "name": "lang", + "in": "query", + "description": "Optional two character language specifier for the app description. Will be empty if not provided.", + "schema": { + "type": "string" + }, + "example": "en" + } + ], + "responses": { + "200": { + "description": "Returns the requested app details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppDetailResponse" + } + } + } + }, + "404": { + "description": "App not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps": { + "post": { + "tags": [ + "Apps" + ], + "summary": "Creates an app according to input model. (Authorization required - Roles: add_apps)", + "description": "Example: POST: /api/apps", + "requestBody": { + "description": "Input model for app creation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInputModel" + } + } + } + }, + "responses": { + "201": { + "description": "Returns created app's ID.", + "content": { + "application/json": { + "schema": { + "type": "string", + "format": "uuid" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/favourites": { + "get": { + "tags": [ + "Apps" + ], + "summary": "Retrieves IDs of all favourite apps of the current user (by sub claim). (Authorization required - Roles: view_apps)", + "description": "Example: GET: /api/apps/favourites", + "responses": { + "200": { + "description": "Returns the list of favourite apps of current user.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + } + } + } + }, + "400": { + "description": "If sub claim is empty/invalid." + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/{appId}/favourite": { + "post": { + "tags": [ + "Apps" + ], + "summary": "Adds an app to current user's favourites. (Authorization required - Roles: view_apps)", + "description": "Example: POST: /api/apps/D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645/favourite", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "ID of the app to add to user favourites.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645" + } + ], + "responses": { + "204": { + "description": "Favourite app was successfully added to user." + }, + "400": { + "description": "If sub claim is empty/invalid or user does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + }, + "delete": { + "tags": [ + "Apps" + ], + "summary": "Removes an app from current user's favourites. (Authorization required - Roles: view_apps)", + "description": "Example: DELETE: /api/apps/D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645/favourite", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "ID of the app to remove from user favourites.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645" + } + ], + "responses": { + "204": { + "description": "Favourite app was successfully removed from user." + }, + "400": { + "description": "If sub claim is empty/invalid or user does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/subscribed/subscription-status": { + "get": { + "tags": [ + "Apps" + ], + "summary": "Retrieves subscription statuses of subscribed apps of the currently logged in user's company. (Authorization required - Roles: view_subscription)", + "description": "Example: GET: /api/apps/subscribed/subscription-status", + "responses": { + "200": { + "description": "Returns list of applicable app subscription statuses.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GuidOfferSubscriptionStatusIdValueTuple" + } + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/provided/subscription-status": { + "get": { + "tags": [ + "Apps" + ], + "summary": "Retrieves subscription statuses of provided apps of the currently logged in user's company. (Authorization required - Roles: view_app_subscription)", + "description": "Example: GET: /api/apps/provided/subscription-status", + "parameters": [ + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "default": 0 + } + }, + { + "name": "size", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "default": 15 + } + }, + { + "name": "sorting", + "in": "query", + "schema": { + "$ref": "#/components/schemas/SubscriptionStatusSorting" + } + }, + { + "name": "statusId", + "in": "query", + "schema": { + "$ref": "#/components/schemas/OfferSubscriptionStatusId" + } + } + ], + "responses": { + "200": { + "description": "Returns list of applicable app subscription statuses.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OfferCompanySubscriptionStatusDataResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/{appId}/subscribe": { + "post": { + "tags": [ + "Apps" + ], + "summary": "Adds an app to current user's company's subscriptions. (Authorization required - Roles: subscribe_apps)", + "description": "Example: POST: /api/apps/D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645/subscribe", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "ID of the app to subscribe to.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645" + } + ], + "requestBody": { + "description": "The agreement consent data", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OfferAgreementConsentData" + } + } + } + } + }, + "responses": { + "204": { + "description": "App was successfully subscribed to." + }, + "400": { + "description": "If sub claim is empty/invalid or user does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "If appId does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/appAgreementData/{appId}": { + "get": { + "tags": [ + "Apps" + ], + "summary": "Gets all agreements (Authorization required - Roles: subscribe_apps)", + "description": "Example: GET: /api/apps/appAgreementData/D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "Id for the app consent to retrieve.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645" + } + ], + "responses": { + "200": { + "description": "Returns the app agreement data.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgreementData" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/{appId}/subscription/company/{companyId}/activate": { + "put": { + "tags": [ + "Apps" + ], + "summary": "Activates a pending app subscription for an app provided by the current user's company. (Authorization required - Roles: activate_subscription)", + "description": "Example: PUT: /api/apps/D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645/supscription/company/74BA5AEF-1CC7-495F-ABAA-CF87840FA6E2/activate", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "ID of the app to activate subscription for.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645" + }, + { + "name": "companyId", + "in": "path", + "description": "ID of the company to activate subscription for.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "74BA5AEF-1CC7-495F-ABAA-CF87840FA6E2" + } + ], + "responses": { + "204": { + "description": "App subscription was successfully activated." + }, + "400": { + "description": "If sub claim is empty/invalid or user does not exist, or any other parameters are invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "App does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "App Name not set.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/{appId}/unsubscribe": { + "put": { + "tags": [ + "Apps" + ], + "summary": "Unsubscribes an app from the current user's company's subscriptions. (Authorization required - Roles: unsubscribe_apps)", + "description": "Example: PUT: /api/apps/D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645/unsubscribe", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "ID of the app to unsubscribe from.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "D3B1ECA2-6148-4008-9E6C-C1C2AEA5C645" + } + ], + "responses": { + "204": { + "description": "The app was successfully unsubscribed from." + }, + "400": { + "description": "Either the sub claim is empty/invalid, user does not exist or the subscription might not have the correct status or the companyID is incorrect.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "App does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/provided": { + "get": { + "tags": [ + "Apps" + ], + "summary": "Get all company owned apps. (Authorization required - Roles: app_management)", + "description": "Example: GET: /api/apps/provided", + "responses": { + "200": { + "description": "Returns list of apps provided by the user assigned company.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AllOfferData" + } + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/autoSetup": { + "post": { + "tags": [ + "Apps" + ], + "summary": "Auto setup the app (Authorization required - Roles: activate_subscription)", + "description": "Example: POST: /api/apps/autoSetup", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OfferAutoSetupData" + } + } + } + }, + "responses": { + "200": { + "description": "Returns the app agreement data.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OfferAutoSetupResponseData" + } + } + } + }, + "400": { + "description": "Offer Subscription is pending or not the providing company.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "Offer Subscription not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/{appId}/deactivateApp": { + "put": { + "tags": [ + "Apps" + ], + "summary": "Deactivate the OfferStatus By appId (Authorization required - Roles: edit_apps)", + "description": "Example: PUT: /api/apps/3c77a395-a7e7-40f2-a519-ac16498e0a79/deactivateApp", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "Id of the app that should be deactive", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "3c77a395-a7e7-40f2-a519-ac16498e0a79" + } + ], + "responses": { + "204": { + "description": "The App Successfully Deactivated" + }, + "400": { + "description": "invalid or user does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "If app does not exists.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Missing Permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Offer is in incorrect state", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/{appId}/appDocuments/{documentId}": { + "get": { + "tags": [ + "Apps" + ], + "summary": "Retrieve Document Content for document type \"App Lead Image\" and \"App Image\" by ID (Authorization required - Roles: view_documents)", + "description": "Example: GET: /api/apps/{appId}/appDocuments/{documentId}", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "documentId", + "in": "path", + "description": "", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Returns the document Content", + "content": { + "image/jpeg": { + "schema": { + "type": "string", + "format": "binary" + } + }, + "image/png": { + "schema": { + "type": "string", + "format": "binary" + } + }, + "image/gif": { + "schema": { + "type": "string", + "format": "binary" + } + }, + "image/svg+xml": { + "schema": { + "type": "string", + "format": "binary" + } + }, + "image/tiff": { + "schema": { + "type": "string", + "format": "binary" + } + }, + "application/pdf": { + "schema": { + "type": "string", + "format": "binary" + } + }, + "application/json": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "Document / App id not found or document type not supported.", + "content": { + "image/jpeg": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/png": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/gif": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/svg+xml": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/tiff": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "application/pdf": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "document not found.", + "content": { + "image/jpeg": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/png": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/gif": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/svg+xml": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/tiff": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "application/pdf": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "415": { + "description": "UnSupported Media Type.", + "content": { + "image/jpeg": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/png": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/gif": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/svg+xml": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "image/tiff": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "application/pdf": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/{appId}/appupdate/description": { + "get": { + "tags": [ + "Apps" + ], + "summary": "Get description of the app by Id. (Authorization required - Roles: edit_apps)", + "description": "Example: Get: /api/apps/092bdae3-a044-4314-94f4-85c65a09e31b/appupdate/description", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "Id for the app description to retrieve.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "092bdae3-a044-4314-94f4-85c65a09e31b" + } + ], + "responses": { + "200": { + "description": "returns list of app descriptions", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LocalizedDescription" + } + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + }, + "put": { + "tags": [ + "Apps" + ], + "summary": "Create or Update description of the app by Id. (Authorization required - Roles: edit_apps)", + "description": "Example: Put: /api/apps/092bdae3-a044-4314-94f4-85c65a09e31b/appupdate/description", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "Id for the app description to create or update.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "092bdae3-a044-4314-94f4-85c65a09e31b" + } + ], + "requestBody": { + "description": "app description data to create or update.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LocalizedDescription" + } + } + } + } + }, + "responses": { + "204": { + "description": "The app description succesFully created or updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NoContentResult" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + }, + "/api/Apps/{appId}/appLeadImage": { + "post": { + "tags": [ + "Apps" + ], + "summary": "Create offerassigned AppLeadImage document for active apps for given appId for same company as user (Authorization required - Roles: edit_apps)", + "description": "Example: POST: /api/apps/{appId}/appLeadImage", + "parameters": [ + { + "name": "appId", + "in": "path", + "description": "", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "document": { + "type": "string", + "format": "binary" + } + } + }, + "encoding": { + "ContentType": { + "style": "form" + }, + "ContentDisposition": { + "style": "form" + }, + "Headers": { + "style": "form" + }, + "Length": { + "style": "form" + }, + "Name": { + "style": "form" + }, + "FileName": { + "style": "form" + } + } + }, + "application/json": { + "schema": { + "type": "object", + "properties": { + "document": { + "type": "string", + "format": "binary" + } + } + }, + "encoding": { + "ContentType": { + "style": "form" + }, + "ContentDisposition": { + "style": "form" + }, + "Headers": { + "style": "form" + }, + "Length": { + "style": "form" + }, + "Name": { + "style": "form" + }, + "FileName": { + "style": "form" + } + } + } + } + }, + "responses": { + "204": { + "description": "Successfully uploaded the document", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NoContentResult" + } + } + } + }, + "400": { + "description": "If sub claim is empty/invalid or user does not exist, or any other parameters are invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "The user is not assigned with the app.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "415": { + "description": "Only PNG and JPEG files are supported.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error" + }, + "401": { + "description": "The User is unauthorized" + } + } + } + } + }, + "components": { + "schemas": { + "AgreementConsentStatus": { + "type": "object", + "properties": { + "agreementId": { + "type": "string", + "format": "uuid" + }, + "consentStatus": { + "$ref": "#/components/schemas/ConsentStatusId" + } + }, + "additionalProperties": false + }, + "AgreementData": { + "type": "object", + "properties": { + "agreementId": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string", + "nullable": true + } + }, + "additionalProperties": false + }, + "AgreementDocumentData": { + "type": "object", + "properties": { + "agreementId": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string", + "nullable": true + }, + "documentId": { + "type": "string", + "format": "uuid", + "nullable": true + } + }, + "additionalProperties": false + }, + "AllOfferData": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string", + "nullable": true + }, + "leadPictureId": { + "type": "string", + "format": "uuid" + }, + "provider": { + "type": "string", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/OfferStatusId" + }, + "lastChanged": { + "type": "string", + "format": "date-time", + "nullable": true + } + }, + "additionalProperties": false + }, + "AppData": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Id of the App.", + "format": "uuid" + }, + "name": { + "type": "string", + "description": "Name of the app.", + "nullable": true + }, + "shortDescription": { + "type": "string", + "description": "Short description.", + "nullable": true + }, + "provider": { + "type": "string", + "description": "Provider.", + "nullable": true + }, + "price": { + "type": "string", + "description": "Price.", + "nullable": true + }, + "leadPictureId": { + "type": "string", + "description": "Lead pircture Id.", + "format": "uuid" + }, + "useCases": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The apps use cases.", + "nullable": true + } + }, + "additionalProperties": false, + "description": "View model of an application's base data." + }, + "AppDetailResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ID of the app.", + "format": "uuid" + }, + "title": { + "type": "string", + "description": "Title or name of the app.", + "nullable": true + }, + "leadPictureId": { + "type": "string", + "description": "Uri to app's lead picture.", + "format": "uuid" + }, + "images": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "description": "List of Images to app's secondary pictures.", + "nullable": true + }, + "providerUri": { + "type": "string", + "description": "Uri to provider's marketing presence.", + "nullable": true + }, + "provider": { + "type": "string", + "description": "Provider of the app.", + "nullable": true + }, + "contactEmail": { + "type": "string", + "description": "Email address of the app's primary contact.", + "nullable": true + }, + "contactNumber": { + "type": "string", + "description": "Phone number of the app's primary contact.", + "nullable": true + }, + "useCases": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AppUseCaseData" + }, + "description": "Names of the app's use cases.", + "nullable": true + }, + "longDescription": { + "type": "string", + "description": "Long description of the app.", + "nullable": true + }, + "price": { + "type": "string", + "description": "Pricing information of the app.", + "nullable": true + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Tags assigned to application.", + "nullable": true + }, + "isSubscribed": { + "$ref": "#/components/schemas/OfferSubscriptionStatusId" + }, + "languages": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Languages that the app is available in.", + "nullable": true + }, + "documents": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentData" + } + }, + "description": "documents assigned to offer", + "nullable": true + }, + "privacyPolicies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PrivacyPolicyId" + }, + "description": "Privacy Policies assigned to offer", + "nullable": true + } + }, + "additionalProperties": false, + "description": "View model of an application's detailed data." + }, + "AppEditableDetail": { + "type": "object", + "properties": { + "descriptions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LocalizedDescription" + }, + "description": "", + "nullable": true + }, + "providerUri": { + "type": "string", + "description": "", + "nullable": true + }, + "contactEmail": { + "type": "string", + "description": "", + "nullable": true + }, + "contactNumber": { + "type": "string", + "description": "", + "nullable": true + } + }, + "additionalProperties": false, + "description": "Model for updating an app." + }, + "AppInputModel": { + "type": "object", + "properties": { + "title": { + "maxLength": 255, + "type": "string", + "description": "Title or name of the app.", + "nullable": true + }, + "provider": { + "maxLength": 255, + "type": "string", + "description": "Provider of the app.", + "nullable": true + }, + "providerUri": { + "maxLength": 255, + "type": "string", + "description": "Uri to provider's marketing presence.", + "nullable": true + }, + "appUri": { + "maxLength": 255, + "type": "string", + "description": "Uri for app access.", + "nullable": true + }, + "leadPictureUri": { + "maxLength": 255, + "type": "string", + "description": "Uri to app's lead picture.", + "nullable": true + }, + "contactEmail": { + "maxLength": 255, + "type": "string", + "description": "Email address of the app's primary contact.", + "nullable": true + }, + "contactNumber": { + "maxLength": 255, + "type": "string", + "description": "Phone number of the app's primary contact.", + "nullable": true + }, + "providerCompanyId": { + "type": "string", + "description": "ID of the app's providing company.", + "format": "uuid", + "nullable": true + }, + "salesManagerId": { + "type": "string", + "description": "ID of the app's sales manager.", + "format": "uuid", + "nullable": true + }, + "useCaseIds": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "description": "IDs of app's use cases.", + "nullable": true + }, + "descriptions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LocalizedDescription" + }, + "description": "Descriptions of the app in different languages.", + "nullable": true + }, + "supportedLanguageCodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Two character language codes for the app's supported languages.", + "nullable": true + }, + "price": { + "type": "string", + "description": "Pricing information of the app.", + "nullable": true + } + }, + "additionalProperties": false, + "description": "Model for requesting creation of an application." + }, + "AppProviderResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "title of the offer", + "nullable": true + }, + "provider": { + "type": "string", + "description": "provider name", + "nullable": true + }, + "leadPictureId": { + "type": "string", + "description": "id of the lead picture", + "format": "uuid" + }, + "providerName": { + "type": "string", + "description": "provider name", + "nullable": true + }, + "useCase": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AppUseCaseData" + }, + "description": "list of use cases", + "nullable": true + }, + "descriptions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LocalizedDescription" + }, + "description": "the offer descriptions", + "nullable": true + }, + "agreements": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OfferAgreement" + }, + "description": "the assigned agreements", + "nullable": true + }, + "supportedLanguageCodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the supported language codes", + "nullable": true + }, + "price": { + "type": "string", + "description": "the app price", + "nullable": true + }, + "images": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "description": "list of the images", + "nullable": true + }, + "providerUri": { + "type": "string", + "description": "the provider uri", + "nullable": true + }, + "contactEmail": { + "type": "string", + "description": "contact email", + "nullable": true + }, + "contactNumber": { + "type": "string", + "description": "contact number", + "nullable": true + }, + "documents": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentData" + } + }, + "description": "list of linked documents", + "nullable": true + }, + "salesManagerId": { + "type": "string", + "description": "id of the salesmanager", + "format": "uuid", + "nullable": true + }, + "privacyPolicies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PrivacyPolicyId" + }, + "description": "the privacy policies", + "nullable": true + } + }, + "additionalProperties": false, + "description": "Response for the app creation" + }, + "AppRequestModel": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Title", + "nullable": true + }, + "provider": { + "type": "string", + "description": "Provider", + "nullable": true + }, + "salesManagerId": { + "type": "string", + "description": "SalesManagerId", + "format": "uuid", + "nullable": true + }, + "useCaseIds": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "description": "UseCaseIds", + "nullable": true + }, + "descriptions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LocalizedDescription" + }, + "description": "Descriptions", + "nullable": true + }, + "supportedLanguageCodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "SupportedLanguageCodes", + "nullable": true + }, + "price": { + "type": "string", + "description": "Price", + "nullable": true + }, + "privacyPolicies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PrivacyPolicyId" + }, + "description": "Price", + "nullable": true + }, + "providerUri": { + "type": "string", + "description": "Price", + "nullable": true + }, + "contactEmail": { + "type": "string", + "description": "Price", + "nullable": true + }, + "contactNumber": { + "type": "string", + "description": "Price", + "nullable": true + } + }, + "additionalProperties": false, + "description": "Request Model for App Creation." + }, + "AppRoleData": { + "type": "object", + "properties": { + "roleId": { + "type": "string", + "description": "", + "format": "uuid" + }, + "roleName": { + "type": "string", + "description": "", + "nullable": true + } + }, + "additionalProperties": false, + "description": "Model for Role Data" + }, + "AppUseCaseData": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "label": { + "type": "string", + "nullable": true + } + }, + "additionalProperties": false + }, + "AppUserRole": { + "type": "object", + "properties": { + "role": { + "type": "string", + "description": "", + "nullable": true + }, + "descriptions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AppUserRoleDescription" + }, + "description": "", + "nullable": true + } + }, + "additionalProperties": false, + "description": "Model for Input Role" + }, + "AppUserRoleDescription": { + "type": "object", + "properties": { + "languageCode": { + "type": "string", + "description": "", + "nullable": true + }, + "description": { + "type": "string", + "description": "", + "nullable": true + } + }, + "additionalProperties": false, + "description": "Model for Role Description" + }, + "BusinessAppData": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string", + "nullable": true + }, + "uri": { + "type": "string", + "nullable": true + }, + "leadPictureId": { + "type": "string", + "format": "uuid" + }, + "provider": { + "type": "string", + "nullable": true + } + }, + "additionalProperties": false + }, + "ClientInfoData": { + "type": "object", + "properties": { + "clientId": { + "type": "string", + "nullable": true + } + }, + "additionalProperties": false + }, + "CompanySubscriptionStatusData": { + "type": "object", + "properties": { + "companyId": { + "type": "string", + "format": "uuid" + }, + "companyName": { + "type": "string", + "nullable": true + }, + "subscriptionId": { + "type": "string", + "format": "uuid" + }, + "offerSubscriptionStatus": { + "$ref": "#/components/schemas/OfferSubscriptionStatusId" + } + }, + "additionalProperties": false + }, + "CompanyUserNameData": { + "type": "object", + "properties": { + "userId": { + "type": "string", + "format": "uuid" + }, + "firstName": { + "type": "string", + "nullable": true + }, + "lastName": { + "type": "string", + "nullable": true + } + }, + "additionalProperties": false + }, + "ConsentStatusData": { + "type": "object", + "properties": { + "agreementId": { + "type": "string", + "format": "uuid" + }, + "consentStatus": { + "$ref": "#/components/schemas/ConsentStatusId" + } + }, + "additionalProperties": false + }, + "ConsentStatusId": { + "enum": [ + "ACTIVE", + "INACTIVE" + ], + "type": "string" + }, + "DocumentData": { + "type": "object", + "properties": { + "documentId": { + "type": "string", + "format": "uuid" + }, + "documentName": { + "type": "string", + "nullable": true + } + }, + "additionalProperties": false + }, + "DocumentTypeId": { + "enum": [ + "CX_FRAME_CONTRACT", + "COMMERCIAL_REGISTER_EXTRACT", + "APP_CONTRACT", + "CONFORMITY_APPROVAL_REGISTRATION", + "ADDITIONAL_DETAILS", + "APP_LEADIMAGE", + "APP_IMAGE", + "SELF_DESCRIPTION", + "APP_TECHNICAL_INFORMATION", + "CONFORMITY_APPROVAL_CONNECTOR", + "CONFORMITY_APPROVAL_BUSINESS_APPS", + "CONFORMITY_APPROVAL_SERVICES", + "SERVICE_LEADIMAGE" + ], + "type": "string" + }, + "ErrorResponse": { + "type": "object", + "properties": { + "type": { + "type": "string", + "nullable": true + }, + "title": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer", + "format": "int32" + }, + "errors": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + }, + "nullable": true + } + }, + "additionalProperties": false + }, + "GuidOfferSubscriptionStatusIdValueTuple": { + "type": "object", + "additionalProperties": false + }, + "IActionResult": { + "type": "object", + "additionalProperties": false + }, + "InReviewAppData": { + "type": "object", + "properties": { + "appId": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string", + "nullable": true + }, + "provider": { + "type": "string", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/OfferStatusId" + } + }, + "additionalProperties": false + }, + "InReviewAppDataResponse": { + "type": "object", + "properties": { + "meta": { + "$ref": "#/components/schemas/Metadata" + }, + "content": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InReviewAppData" + }, + "nullable": true + } + }, + "additionalProperties": false + }, + "InReviewAppDetails": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ID of the app.", + "format": "uuid" + }, + "title": { + "type": "string", + "description": "Title or name of the app.", + "nullable": true + }, + "leadPictureId": { + "type": "string", + "description": "Uri to app's lead picture.", + "format": "uuid" + }, + "images": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "description": "List of Images to app's secondary pictures.", + "nullable": true + }, + "provider": { + "type": "string", + "description": "Provider of the app.", + "nullable": true + }, + "useCases": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Names of the app's use cases.", + "nullable": true + }, + "description": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LocalizedDescription" + }, + "description": "description of the app.", + "nullable": true + }, + "documents": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentData" + } + }, + "description": "documents assigned to offer", + "nullable": true + }, + "roles": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Roles assigned to offer", + "nullable": true + }, + "languages": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Languages that the app is available in.", + "nullable": true + }, + "providerUri": { + "type": "string", + "description": "Uri to provider's marketing presence.", + "nullable": true + }, + "contactEmail": { + "type": "string", + "description": "Email address of the app's primary contact.", + "nullable": true + }, + "contactNumber": { + "type": "string", + "description": "Phone number of the app's primary contact.", + "nullable": true + }, + "price": { + "type": "string", + "description": "Pricing information of the app.", + "nullable": true + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Tags assigned to application.", + "nullable": true + } + }, + "additionalProperties": false, + "description": "View model of an application's detailed data." + }, + "LocalizedDescription": { + "type": "object", + "properties": { + "languageCode": { + "type": "string", + "nullable": true + }, + "longDescription": { + "type": "string", + "nullable": true + }, + "shortDescription": { + "type": "string", + "nullable": true + } + }, + "additionalProperties": false + }, + "Metadata": { + "type": "object", + "properties": { + "totalElements": { + "type": "integer", + "format": "int32" + }, + "totalPages": { + "type": "integer", + "format": "int32" + }, + "page": { + "type": "integer", + "format": "int32" + }, + "contentSize": { + "type": "integer", + "format": "int32" + } + }, + "additionalProperties": false + }, + "NoContentResult": { + "type": "object", + "properties": { + "statusCode": { + "type": "integer", + "format": "int32" + } + }, + "additionalProperties": false + }, + "OfferAgreement": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "nullable": true + }, + "name": { + "type": "string", + "nullable": true + }, + "consentStatus": { + "type": "string", + "nullable": true + } + }, + "additionalProperties": false + }, + "OfferAgreementConsent": { + "type": "object", + "properties": { + "agreements": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgreementConsentStatus" + }, + "nullable": true + } + }, + "additionalProperties": false + }, + "OfferAgreementConsentData": { + "type": "object", + "properties": { + "agreementId": { + "type": "string", + "format": "uuid" + }, + "consentStatusId": { + "$ref": "#/components/schemas/ConsentStatusId" + } + }, + "additionalProperties": false + }, + "OfferAutoSetupData": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "format": "uuid" + }, + "offerUrl": { + "type": "string", + "nullable": true + } + }, + "additionalProperties": false + }, + "OfferAutoSetupResponseData": { + "type": "object", + "properties": { + "technicalUserInfo": { + "$ref": "#/components/schemas/TechnicalUserInfoData" + }, + "clientInfo": { + "$ref": "#/components/schemas/ClientInfoData" + } + }, + "additionalProperties": false + }, + "OfferCompanySubscriptionStatusData": { + "type": "object", + "properties": { + "offerId": { + "type": "string", + "format": "uuid" + }, + "serviceName": { + "type": "string", + "nullable": true + }, + "companySubscriptionStatuses": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CompanySubscriptionStatusData" + }, + "nullable": true + } + }, + "additionalProperties": false + }, + "OfferCompanySubscriptionStatusDataResponse": { + "type": "object", + "properties": { + "meta": { + "$ref": "#/components/schemas/Metadata" + }, + "content": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OfferCompanySubscriptionStatusData" + }, + "nullable": true + } + }, + "additionalProperties": false + }, + "OfferDeclineRequest": { + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + } + }, + "additionalProperties": false + }, + "OfferSorting": { + "enum": [ + "DateAsc", + "DateDesc", + "NameAsc", + "NameDesc" + ], + "type": "string" + }, + "OfferStatusId": { + "enum": [ + "CREATED", + "IN_REVIEW", + "ACTIVE", + "INACTIVE" + ], + "type": "string" + }, + "OfferStatusIdFilter": { + "enum": [ + "InReview", + "All" + ], + "type": "string", + "description": "Filters the OfferStatusId information" + }, + "OfferSubscriptionStatusId": { + "enum": [ + "PENDING", + "ACTIVE", + "INACTIVE" + ], + "type": "string" + }, + "PrivacyPolicyData": { + "type": "object", + "properties": { + "privacyPolicies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PrivacyPolicyId" + }, + "description": "Privacy Policy.", + "nullable": true + } + }, + "additionalProperties": false, + "description": "model of Privacy Policy data." + }, + "PrivacyPolicyId": { + "enum": [ + "COMPANY_DATA", + "USER_DATA", + "LOCATION", + "BROWSER_HISTORY", + "NONE" + ], + "type": "string" + }, + "SubscriptionStatusSorting": { + "enum": [ + "CompanyNameAsc", + "CompanyNameDesc", + "OfferIdAsc", + "OfferIdDesc" + ], + "type": "string" + }, + "TechnicalUserInfoData": { + "type": "object", + "properties": { + "technicalUserId": { + "type": "string", + "format": "uuid" + }, + "technicalUserSecret": { + "type": "string", + "nullable": true + }, + "technicalClientId": { + "type": "string", + "nullable": true + } + }, + "additionalProperties": false + } + }, + "securitySchemes": { + "Bearer": { + "type": "apiKey", + "description": "JWT Authorization header using the Bearer scheme. \r\n\r\n Enter 'Bearer' [space] and then your token in the text input below.\r\n\r\nExample: \"Bearer 12345abcdef\"", + "name": "Authorization", + "in": "header" + } + } + }, + "security": [ + { + "Bearer": [ ] + } + ] +} \ No newline at end of file diff --git a/docs/standards/CX-0055-DataProcessingPatternsforITSystemIntegration/CX-0055-DataProcessingPatternsforITSystemIntegration.md b/docs/standards/CX-0055-DataProcessingPatternsforITSystemIntegration/CX-0055-DataProcessingPatternsforITSystemIntegration.md new file mode 100644 index 000000000..09157be8c --- /dev/null +++ b/docs/standards/CX-0055-DataProcessingPatternsforITSystemIntegration/CX-0055-DataProcessingPatternsforITSystemIntegration.md @@ -0,0 +1,166 @@ +# CX-0055 Data Processing Patterns for IT System Integration v1.1.0 + +## ABSTRACT + +This document provides specific conformity assessment criteria for IT-System Integration solutions that +connect arbitrary backend applications to Catena-X for both, data provisioning and data consumption. +Depending on the use-case, different standards must be fulfilled for data provisioning and consumption. +Thus, this document is modular and describes criteria for different schemes of data provisioning +and consumption (so called data processing patterns) in order to enable use case agnostic certification +of IT-system integration solutions. +Data Providers and Consumers can either implement the set of relevant standard themselves, +or use a managed solution that implements the standards. +This standard is particularly addressing the second case. + +## 1. INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This document is relevant for: + +- Enablement Service Provider + +This document is in particular relevant for enablement service providers who are offering a (managed) solution for IT-system integration. +Those solutions offer the capability to provide data to Catena-X (or consume Catena-X data vice versa) by offering automated data pipelines. +This very basic capability provides a cornerstone for different Catena-X use cases. + +This standard addresses in particular the interfaces which IT-System Integration Solutions expose +to exchange data with Catena-X. +For this standard, offered interfaces need to be compliant to technical standards that are used +by Catena-X to manage data processing (e.g. EDC, AAS or SAMM). +The IT-System Integration Solution itself is out of scope. + +Furthermore, the document can be used as a guideline for data providers/consumers who want to connect +backend systems/middlewares etc. +with Catena-X via a custom build setup (without the need of certification in this case). + +Out of scope for this document are small scale data provisioning solutions suiting the particular +needs of SME (e.g. working with exchange formats only, such as "Simple Data Exchanger"). +Refer to CX-0007 for a certification of minimal data provider service offerings. + +This document does not contain references to external standards and Catena-X guardrails +that need to be fulfilled for the listing of apps into the Catena-X marketplace such as an ISO27001 +certification or the passing of certain penetration tests. +Nevertheless, IT-System Integration solutions will also need to pass those conformity assessments. + +### 1.2 CONTEXT + +> *This section is non-normative* + +Data provisioning/consumption in Catena-X can be done in multiple ways. +There are i.e. simple upload tools for SMEs which only need to provide data in small batches upon request. +For a steady supply of data however, different solutions are necessary. +Connecting backend systems, transforming semantic models and finally providing data +in the right format and via the right channels (IDS Protocol) are some of the tasks that need to be done. +IT-System Integration Solutions support companies with this task. + +Depending on the Catena-X use case, there may be different sets of standards required to specify data exchange. +One Catena-X use case may require a combination of EDC, AAS and SAMM +while another Catena-X use case may only utilize EDC to handle data exchange between companies. +Those alternative combinations of standards for data processing are defined as "data processing patterns" in the scope of this document. + +Enablement Service Providers need to show compliance of System Integration Solutions to data processing patterns in order to receive certification for Catena-X use cases (that utilize respective patterns). + +Example: + +- Use case A (e.g. Circular Economy - Dismantler Dashboard) and use case B (e.g. Sustainability - CO2 Footprint) utilize Data Processing Pattern 1 (e.g. combination of EDC, SAMM and AAS) +- a Backend Integration Solution X is certified against Data Processing Pattern 1 +- As a result of the certification, Backend Integration Solution X can be utilized for use cases A and B. + +Except those patterns, interfaces provided by IT-System Integration Solutions are agnostic for Catena-X use-cases in a sense, +that they don't contain any use-case specific business logic. Thus, an IT-System Integration solution can be certified for being utilized across different use cases (without considering additional use-case specific standards). + +### 1.3 ARCHITECTURE OVERVIEW + +> *This section is non-normative* + +Figure 1 gives an idea about the scope of conformity assessment for IT-System Integration solutions in Catena-X. The data source/sink refers to a company IT landscape. +Thus, it can comprise one IT-system, (such as ERP or PLM) or multiple systems, data lakes etc. +To make this data accessible for Catena-X (or vice versa to write Catena-X data into backend systems) +a dedicated tool or toolchain is necessary. +Since IT-architectures and IT-System Integration solutions vary significantly between different companies, +no standard can be applied here (see also *Data Integration Patterns Guide* on Catena-X website for further information). +Thus, conformity assessment for IT-System Integration solutions focuses on requirements for data formats, and data transfer protocols (Catena-X interface, see Figure 1 marked in blue). +The IT-System Integration solution itself is out of scope for this standard. + +![backend-solutions-arch.png](./assets/backend-solutions-arch.png) + +Figure 1: Scope of conformity assessment - Catena-X interface for IT-System Integration solutions + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they are conform with the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). +Please refer to the association homepage for the process of conformity assessment and certification. + +To proof the overall conformity of an IT-System Integration solution for Catena-X use-cases, +a proof of conformity for standards belonging to a specific Data Processing Pattern (listed in section 2) has to be obtained. + +## 2. STANDARDS FOR DATA PROCESSING PATTERNS + +> *This section is normative* + +This chapter describes possible ways for providing data for Catena-X (and to consume it respectively). IT-System Integration solutions MUST fulfill the standards for at least one Data Processing Pattern in order to obtain a certificate for this standard. +The certificate issued by CAB MUST specify for which data processing pattern(s) the IT-System Integration solution was succesfully evaluated in the certification process. The IT-System Integration solution can then only be utilized for Catena-X use case applications that make use of the specific Data Processing Patterns that were in scope of certification. + +The following list of Data Processing Patterns will be extended as soon as new patterns emerge +and respective Catena-X standards are available. + +- All solutions in this chapter MUST implement the standard CX – 0018 Sovereign Data Exchange v 1.0.1 + +### 2.1 LIST OF STANDALONE STANDARDS + +> *This section is normative* + +**Data Processing Pattern 1** (SAMM and AAS): All solutions that shall be used for data provisioning/data consumption for use-cases using SAMM and AAS MUST implement the following standards: + +- CX-0002 Digital Twins in Catena - X v 1.0.2 +- CX-0003 SAMM Aspect Meta Model v 1.0.2 + +This includes, but is not limited to the following use-cases: + +- Traceability +- Circular Economy +- Sustainability + +**Data Processing Pattern 2** (Knowledge Agents): All solutions that shall be used for data provisioning/data consumption for use-cases using Knowledge Agents MUST implement the following standards: + +- CX-0084 Federated Queries in Data Spaces (Knowledge Agents) v1.0.0 + +This includes, but is not limited to the following use-cases: + +- Behaviour Twin + +Note: It is up to the data provider to provide the data +in the correct semantic models for a specific use-case. +Those models can be found in the specific use-case standards. +The IT-System Integration solution only needs to proof that it enables +the data provider to provide the data in the correct semantic modelling language. + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +- CX–0018 Sovereign Data Exchange v 1.0.1 +- CX-0002 Digital Twins in Catena-X v 1.0.2 +- CX-0003 SAMM Aspect Meta Model v 1.0.2 +- CX-0084 Federated Queries in Data Spaces (Knowledge Agents) v1.0.0 + +## ANNEXES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0055-DataProcessingPatternsforITSystemIntegration/assets/backend-solutions-arch.png b/docs/standards/CX-0055-DataProcessingPatternsforITSystemIntegration/assets/backend-solutions-arch.png new file mode 100644 index 000000000..3379b5748 Binary files /dev/null and b/docs/standards/CX-0055-DataProcessingPatternsforITSystemIntegration/assets/backend-solutions-arch.png differ diff --git a/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/CX-0059-UseCaseBehaviourTwinEndurancePredictor.md b/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/CX-0059-UseCaseBehaviourTwinEndurancePredictor.md new file mode 100644 index 000000000..84a6f2067 --- /dev/null +++ b/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/CX-0059-UseCaseBehaviourTwinEndurancePredictor.md @@ -0,0 +1,788 @@ +# CX-0059 Use Case Behaviour Twin Endurance Predictor v2.0.0 + +## ABSTRACT + +Behavioral product models, built on a consistent architecture of reusable functional components within ecosystems like Catena-X, unlock a wide range of innovative business ideas and digital services. + +The focus of the 'data-centric and model-centric development and operational support' revolves around the 'digital behaviour twin'. This concept maps products, their functions, attributes, and business metrics by using a shared data model. + +Part of this digital twin involves dynamic services providing real-time information about existing or planned vehicles. Stakeholders like automobile clubs or recycler seek specific details, such as a component's expected lifespan. This information is crucial for determining the viability of recycling components. + +This standard focuses on the Endurance Predictor. The Endurance predictor receives load spectra, which has been recorded in the vehicle, through the Catena-X network. The load spectra, combined with additional product knowledge by the service provider, is used to calculate precise remaining useful life values for specific components. + +## FOR WHOM IS THE STANDARD DESIGNED + +The standard is relevant for the following roles within the scope of the Endurance Predictor service: + +- data & service provider/consumer +- business application provider + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +This standard upgrades the triangle (previously CX-0059:1.2) to an Use Case Standard and consolidates the contents of the previously independent standards CX-0056, CX-0057 and CX-0058 within a single comprehensive standard. + +## 1 INTRODUCTION + +This document acts as an umbrella for single standards required to request "Remaining Useful Life (RUL)" data as well as providing a service for its calculation at a component level. Included are APIs to be provided by the service provider and the service requester, as well as aspect models for the respective payloads being exchanged in an asynchronous pattern leveraging those APIs. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +The standard is relevant for the following roles within the scope of Endurance Predictor service: + +- data & consumer provider/consumer +- business application provider + +NOTE: Fulfilling a use case standard by a data provider/consumer can be done in two ways: A\) purchase a certified app for the use case. In this case the data provider/consumer does not need to proof conformity again and B\) data provisioning/consumption without a certified app for the use case. In this case the data provider/consumer needs to proof conformity with all single standards listed in this document. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +There are two ways for implementing the Remaining useful Life (RuL) use case: + +1. Using the Knowledge Agent technology. +2. Using the notification based API directly. + +In order to be scalable (multiple partners/components), the preferred way is to use the Knowledge Agent. + +#### 1.2.1 KNOWLEDGE AGENT + +This graphic illustrates the principles architecture of the Endurance Predictor Service using the Knowledge Agent. + +![architecture overview with knowledge agent](./assets/architecture_overview_knowledge_agent.drawio.png) + +Since Data Transfer in Catena-X requires IDSA compliance, both parties involved must use an IDSA compliant connector and +provision the API endpoints as specific data assets in those connectors. + +The Knowledge Agent functionality for the Dataspace Connector is required. This is defined in CX-0084:v1.2 Federated Queries in Data Spaces. + +A standard for a semantic-driven and state-of-the-art compute-to-data architecture for Catena-X, the so-called Knowledge Agents (KA) approach. It builds on well-established W3C-standards of the semantic web. + +Depending on your role, you must provide the following parts of this standard: + +- **all**: + - running Knowledge Agent Dataspace Connector extensions +- **data provider**: + - bindings for load spectra to the knowledge graph, ideally by using a binding agent (see Binding Layer and related examples in CX-0084:v1.2) + - graph asset, which describes and offers the data bindings in a Knowledge Agent compatible way (policies may also be required) + - optional: a RuL skill (if you want to provide simple access to RuL calculations for yourself or for external requesters) +- **service provider** + - bindings for a endurance predictor service (see cx-behaviour:RemainingUsefulLife within the [behaviour ontology](https://w3id.org/catenax/ontology/behaviour)) to the knowledge graph, ideally by using a binding agent + - graph asset, which describes and offers the service bindings in a Knowledge Agent compatible way (policies may also be required) +- **service requester** + - an own RuL skill or a access to a remote skill + +If a service requester requests a RuL value, he invokes the RuL skill and provides a vehicle identification number to it. This can also be done for multiple vehicles at once in a batch mode. The skill is located at or transferred to the data provider. +At the data provider, the data bindings and the service provider are resolved by the Knowledge Agent. Then, the data are transferred to the service provider via Knowledge Agent. There, the RuL value is calculated and passed back to the requester. + +Although it is not mandatory to use the Endurance Predictor API (section 4) and the Aspect models (section 3) in the Knowledge Agent context, it is recommended to do so. + +#### 1.2.2 NOTIFICATION BASED API + +This graphic illustrates the principles architecture of the Endurance Predictor Service using the notification based API. + +![architecture overview with direct API usage](./assets/architecture_overview_notification_based.drawio.png) + +As a data provider you will receive a request for remaining useful life information from an outside RuL service requester via Dataspace Connector. +The data provider, which has the vehicle load spectrum data, forwards them by calling the supplier of the specific part. +After the calculation, the results are transferred back to the data provider through the Dataspace Connector and forwarded to the requester. + +The present standard (CX-0138) contains two aspect models described in detail in Chapter 3. + +1. Aspect Model for load spectra, acting as the main input for a component specific calculation for remaining +useful life. (See section 3.1) +2. Aspect Model for Remaining Useful Life data, acting as the main output for a component specific calculation +for remaining useful life. (See section 3.2) + +It also contains the API descriptions for the APIs to exchange requests as well as results of a remaining useful life calculation: + +1. API Endurance Predictor (contains both API descriptions). (See section 4.1) + +The calculation and data transfers are asynchronous, therefore all parties involved in a calculation request require to provide notification API endpoints, as the results are sent back at a later stage and not as part of the HTTP response body. The notification formats are covered by CX-0023 Notification API. + +Since Data Transfer in Catena-X requires IDSA compliance, both parties involved must use an IDSA compliant connector and +provision the API endpoints as specific data assets in those connectors. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they are conform with the Catena-X standards. To validate that the +standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). +Since this document describes a set of standards to be fulfilled, participants MUST fulfill all mentioned standards and +the respective conformity assessment criteria in addition to the specific criteria mentioned in this document. +The specific criteria described in this document are describing the usage of the central tools as well as common tools described +in the linked standardization documents and therefore compliance should be checked with the tools provided for these +components. +The Tractus-X EDC (Eclipse Dataspace Connector) is RECOMMENDED to be used as an IDSA compliant connector, as it is the current +reference implementation of the IDSA protocol. + +### 1.4 EXAMPLES + +The Endurance Predictor can be used in many different contexts. + +OEM, TIER-X: In the early development phase, components can be designed using digital prototypes based on component-specific damage calculation. The load data required for this comes from simulation or measurement in the digital twin. + +TIER-X: The overall product range becomes more attractive in the offer phase when model-based damage calculation is included as a product-related service. + +During the usage phase, OEMs, car dealers and automotive clubs can further interpret the Remaining Useful Life calculation for a vehicle evaluation and offer it as vehicle-related services for their end customers and fleet operators. + +Even during the usage phase, but particularly during the recycling phase, OEMs, TIER-X, automotive clubs, car dealers, insurers, fleet operators and recyclers benefit from precise residual value analyses of the entire vehicle and its components based on component-specific damage calculation. + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +- **Business Partner Number (BPN):** A BPN is the unique identifier of a partner within Catena-X +- **Tractus-X EDC (Eclipse Dataspace Connector):** The Tractus-X EDC is a reference implementation of a connector for IDSA conform sovereign data exchange +- **Behaviour Twin:** Behavioral product models, based on a structured and consistent architecture of reusable and standard functional components and applied in a common ecosystem. +- **Notification:** Notification - as described in CX-0023 Notification API v1.2.2, are - in contrast to classical data offers in Catena-X - a way to push data from a sender to a receiver and vice versa in asynchronous way. +- **Knowledge Agent (KA):** The so-called Knowledge Agents (KA) approach. It builds on well-established W3C-standards of the semantic web, such as OWL, SPARQL, SHACL, RDF etc. and makes these protocols usable to formulate powerful queries to the data space. Those queries can be used to answer business questions directly (comparable to a search engine) or they can be embedded in apps to include query results into workflows with more advanced visualization. +- **Matchmaking Agent:** This component supports SparQL to traverse the federated data space as a large data structure. It interacts with the Dataspace Connector. + The provider's Matchmaking Agent will be activated by its Dataspace Connector. Therefore, the Dataspace Connector must offer a Graph Asset (variant of ordinary data assets in the Catena-X Dataspace Connectivity standard). + The consumer's Matchmaking Agent interacts with its Dataspace Connector to negotiate and perform the transfer of Sub-Skills to other dataspace participants. + The Matchmaking Agents are matching the (sub)graphs and negotiate appropriated graph assets with the partner Dataspace Connectors. +- **Binding Agent:** The Binding Agent is a restricted version of the Matchmaking Agent (subset of OWL/SparQL, e.g., without federation) which is just focused on translating Sub-Skills of a particular business domain (Bill-Of-Material, Chemical Materials, Production Sites, etc.) into proper SQL- or REST based backend system calls. Implementation details: For data bindings, OnTop is used. For service bindings, RDF4J is used. +- **Ontology:** The ontology is a formal representation of knowledge that captures concepts, relationships, and properties. It allows a shared understanding and reasoning about the respective domain. It must be hosted in a way that all participants can access it. Currently, the ontology is hosted at GitHub. + +Use case specific glossary of used API and SAMM models can be found in the respective sections in this standard document. + +## 2 RELEVANT PARTS OF THE STANDARD "Use Case Behaviour Twin Endurance Predictor" + +> *This section is normative* + +### 2.1 STANDARDS FOR "Use Case Behaviour Twin Endurance Predictor" + +> *This section is normative* + +If using the Knowledge Agent, only external standards are used. The following internal standards only apply when using the notification based API. + +As a Service Provider for an Endurance Predictor Service I need to fulfill the following standards in the following contexts: + +- Semantic Model: Classified load spectrum (Section 3.1) MUST be understood by my service and MUST be consumed by my service provider API. +- Semantic Model: Remaining Useful Life (Section 3.2) MUST be provided as part of my communication of the result towards the requester and/or requesting application. +- API: Endurance Predictor (Section 4.1) MUST be followed in terms of all relevant parts for a service provider. + +As a Service Requester or Service Requester Application I need to fulfill the following standards in the following contexts: + +- Semantic Model: Classified load spectrum (Section 3.1) MUST be provided as part of the request for a remaining useful life calculation towards a service operator's API. +- Semantic Model: Remaining Useful Life (Section 3.2) MUST be consumable by my connected underlying application. +- API: Endurance Predictor (Section 4.1) MUST be followed in terms of all relevant parts for a service requester. + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +To participate in the Use Case Behaviour Twin Endurance Predictor, the following single standards MUST be fulfilled, depending on the usage of the Knowledge Agent: + +- CX-0018:v3.0 Dataspace Connectivity +- CX-0023:v1.2 Notification API (only if using the notification based API) +- CX-0067:v1.1 Ontology Models to realize federated query in Catena-X (only if using the Knowledge Agent) +- CX-0084:v1.2 Federated Queries in Data Spaces (only if using the Knowledge Agent) + +#### 2.1.2 DATA REQUIRED + +As a service requester or service requester application I MUST provide load spectra. If using the notification based API, the data MUST be in the format of the aspect model described in Section 3.1. +As a service provider I MUST provide Remaining useful Life information. If using the notification based API, the results MUST be in the format of the aspect model described in Section 3.2. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### KNOWLEDGE AGENT SPECIFIC REQUIREMENTS + +The following only applies if you use the Knowledge Agent for the RuL use case. + +If you are engaged as a data provider, you MUST mount your data source to the federated knowledge graph as Graph Asset. Beside the policy and contract definition, a Graph Asset registration is needed. +As a service provider you MUST make the service available as part of the federated knowledge graph, a Graph Asset pointing to your Remoting Agent endpoint is needed. + +##### Conventions for Use Case Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository. This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas MUST be followed when providing services or apps for data sharing/consuming. + +##### Additional details regarding Access Policies + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number. + +- Membership +- BPNL + +##### Additional Details regarding Usage Policies + +In the context of data usage policies ("Usage Policies"), Participants and related services MUST use the following policy rules: + +- Use Case Framework ("FrameworkAgreement") +- at least one use case purpose ("UsagePurpose") from the above mentioned ODRL policy repository. + +Additionally, respective usage policies MAY include the following policy rule: + +- Reference Contract ("ContractReference"). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the ODRL policy repository. + +##### Versioning + +Note: Data Assets differentiated only by major version MUST be offered in parallel. The current standard and API versions mark the start of Life Cycle Management in Catena-X operations. Previous versions are dismissed. + +The API version described in this standard document MUST be published in the property [https://w3id.org/catenax/ontology/common#version](https://w3id.org/catenax/ontology/common#version) as version X.Y in dcat:Dataset \([http://www.w3.org/ns/dcat#](http://www.w3.org/ns/dcat#)\). The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. +If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +## 3 ASPECT MODELS + +The following Aspect Models are part of this standard: + +1. ClassifiedLoadSpectrum, V 1.0.0, urn:bamm:io.catenax.classified_load_spectrum:1.0.0 +2. RemainingUsefulLife", V1.0.0, urn:bamm:io.catenax.rul:1.0.0##RemainingUsefulLife + +> *This section is normative* + +### 3.1 ASPECT MODEL "ClassifiedLoadSpectrum" + +#### 3.1.1 INTRODUCTION + +The data model "ClassifiedLoadSpectrum" represents the load data of a vehicle component. +The load spectrum is a data set that represents the aggregated loading of a component. +Any kind of loading is covered: loading can be force or torque or revolutions or temperature or event or similar. The load data is classified and counted with specific counting methods. + +This standard defines the format for the counted load data, so that the exchange of load data between different partners is possible. + +#### 3.1.2 CONTEXT + +> *This section is non-normative* + +The „ClassifiedLoadSpectrum" contains load data, metadata to interpret this load data and the CX ID of the assembly or component these load data are valid for. + +Load spectra counts the loading of a component in classes. Loading can be a change of a state like gearshift, a temperature distribution or the torque acting at a shaft or anything else. In a load spectrum, these loads are classified. The torque acting at a shaft, for example, has an upper and a lower limit: this interval is divided in a number smaller intervals, the classes and torque is sorted is this classes. The counting may be the time the shaft is subjected to the torque or the number of changes of torque classes. + +In the standard, arbitrary number of load channels are possible, but only one counting. For each load channel a vector with the acting load classes must be provided. The first entry in the counts vector is the counting of the combination of loads given in the first entries of the load channel vectors. Only load combinations which occur are stored. So the number of data is minimized. + +All kinds of load data and events can be covered with the standard. The counting might be time or any kind of numbering like number of events or revolutions. + +The metadata block is used to identify the right component in order to interpret the load spectrum. A component is designed for a specific application with a specific loading. To estimate the damage respectively the health of a component, a lifetime model is combined with the load data. The lifetime model is in general property of the component producer. Load data might be measured, simulated or logged during component usage. + +The standard covers all classified load spectra, independent of the origin. The origin is stored in the standard. + +#### 3.1.3 EXAMPLES + +```json +{ +    "targetComponentID": "urn:uuid:1d161134-8bd4-4253-8735-304852d1d17b", +    "metadata": { +        "projectDescription": "projectnumber Stadt", +        "componentDescription": "GearOil", +        "routeDescription": "logged", +        "status": { +          "date": "2022-08-11T10:42:14.213+01:00", +          "operatingHours": 3213.9, +          "mileage": 65432 +        + } + }, +      "header": { +        "countingMethod": "TimeAtLevel", +        "channels": [ +            { +                "channelName": "TC_SU", +                "unit": "unit:degreeCelsius", +                "lowerLimit": 0.0, +                "upperLimit": 640.0, +                "numberOfBins": 128           + } + ], +        "countingValue": "Time", +        "countingUnit": "unit:secondUnitOfTime" + }, +    "body": { + "classes": [ +        { + "className": "TC_SU-class", + "classList": [ + 14, +         15, +         16, +         17, +         18, +         19, +         20, +         21, +         22 + ] + } + ], + "counts": { +        "countsName": "Time", + "countsList": [ + 34968.93, +        73972.51, +        401315.15, +         4675505.56, +         2526898.35, +         864975.95, +         938365.35, +         1918920.77, +         135387.54 + ] + } + } +``` + +#### 3.1.4 TERMINOLOGY + +> *This section is non-normative* + +Aspect Model +: a formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect. + +: Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model. + +: Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +*[Source: Catena-X, CX-0002:v1.2]* + +- "Classified Load Spectrum": Aspect model +- "targetComponentID": CX -ID of the assembly or component for which the load spectrum is valid for. It is necessary to identify the specific component. +- "metadata"/"Metadata": property/entity; Information on component, vehicle, load data origin and vehicle status +- "componentDescription": property; identifier, might be used to find the right lifetime model +- "projectDescription": property; identifier, might be used for information on specific vehicle +- "routeDescription": property; identifier, might be used for information on specific application +- "status"/"StatusEntity": property/entity; actual vehicle status +- "date": property; actual date at which the load spectrum is provided +- "mileage": property; mileage which the load spectrum covers, the unit is [km] +- "operatingHours": property; number of operating hours which the load spectrum covers + +- "header"/"HeaderEntity": property/entity; classification information +- "countingMethod": property; enumeration describing the kind of counting: "Rainflow", "LRD", "EventCount", "TimeAtLevel", "RangeCount", "PeakCount", "MaximumCount". +- "countingValue": property; optional, for example "Time", if time is counted. +- "countingUnit" : property; dependent on counting value "unit: s" for time +- "channels"/"LoadChannelEntity" property/entity; list of load channels. Each list entry contains +- "channelName": property; identifier of channel +- "unit": property; unit of the load, for example "unit: degreeCelsius" or "unit: Nm" +- "lowerLimit": property; lower limit of the load value +- "upperLimit": property; upper limit of the load value +- "numerOfBins": property; number of load classes +- "binLimits": property; optional, if a non-equidistant divisio + +- "body"/"BodySets": property/entity; lists of load dat +- "classes"/"ClassListEntity": property/entity; list of load channels, each entry in the list contains +- "className" : here the channel is characterized by channel name. The name ics extended by "-class". For a rainflow counting, a load channel has two class lists, the channel name must be extended with "_from-class" and "_to-class" +- "classList": list of the load data +- "counts"/"CountsEntity": property/entity; counts name and list +- "countsName": Name of counting, for example "NumberOfRevolutions" or just "Counts" +- "countsList": property; list of the counting according to the classes in same position in "classList" + +- "residuum"/"ResiduumEntity": property/entity; for rainflow counted load spectra, a residuum stores the unclosed hysteresis loops. +- "residuumClassName": property; the name is according to the load channel name +- "residuumClassList": property; the list of turning point classes belonging to unclosed hysteresis loops + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +#### 3.1.5 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#52-non-normative-references). + +This aspect model is written in BAMM 1.0.0 as a modeling language. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.1.6 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.7 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier: + +```text +urn:bamm:io.catenax.classified_load_spectrum:1.0.0 +``` + +This identifier **MUST** be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.8 FORMATS OF SEMANTIC MODEL + +##### 3.1.8.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. The file can be found here: + +[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.classified_load_spectrum/1.0.0/ClassifiedLoadSpectrum.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.classified_load_spectrum/1.0.0/ClassifiedLoadSpectrum.ttl) + +The open-source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +##### 3.1.8.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.1.8.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#52-non-normative-references)\]. + +Note: As soon as the specification V3.0 of the Asset Administration Shell specification is available +an update will be provided. +Template or a HTML documentation. + +### 3.2 ASPECT MODEL "RemainingUsefulLife" + +#### 3.2.1 INTRODUCTION + +The data model Remaining Useful Life contains the two relevant values to describe the expected remaining life of a vehicle, remaining running distance and remaining operating hours. + +The data model is used for vehicle parts and vehicle components which cannot be visually assessed but need the loading information combined with a damage model to estimate the health of the component. + +#### 3.2.2 CONTEXT + +> *This section is non-normative* + +Remaining useful Life is describing the actual health of a vehicle component. Remaining useful Life is defined for vehicle and vehicle components; the values are "remaining running distance" and "remaining operating hours". As it is a short-term property, the status of determination is part of the standard. Remaining useful Life is the result of a service determining the health of a vehicle component from the loading the component was subjected to. This loading might before example measured, simulate or estimated, this information on the origin of the loading is part of the standard. + +![remaining_useful_life.png](./assets/remaing_useful_life.png) +*Figure 1: Overview* + +#### 3.2.3 EXAMPLES + +```json +{ +  "remainingOperatingHours": 2500, +  "remainingRunningDistance": 150000, +  "determinationStatus": { +    "date": "2022-06-15T14:23:56Z", +    "operatingHours": 3456.7, +    "mileage": 204000 +  }, +  "determinationLoaddataSource": { +    "informationOriginLoadSpectrum": "loggedOEM" +  } +} +``` + +#### 3.2.4 TERMINOLOGY + +> *This section is non-normative* + +Aspect Model +: a formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect. + +: Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model. + +: Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +*[Source: Catena-X, CX-0002:v1.2]* + +- RemainingRunningDistance: The estimated number of kilometers, the vehicle can drive without expectable failure of the component. This is an integer number, the unit is [km]. +- Remaining operating hours: Estimated number of operating hours of the vehicle without expectable failure of the component. Floating number, unit is [h]. +- determinationLoaddataSource: The remaining life is estimated from the loading the component was subjected to. The loading of the component might be logged during vehicle life or simulated or estimated: this information on the origin is stored here. If available, the URL of the loadspectrum can be stored here. +- determinationStatus : Comprising "date", "mileage", "operatingHours", the timestamp the remainingUsefulLife was calculated and the according mileage and operating hours of the vehicle. +- sourceLoadSpectrum: if available, the URL of the used load spectrum +- informationOriginLoadSpectrum: enumeration of possible loaddata sources: + - "loggedOEM": the data are collected during usage and provided on OEM side + - "measuredOEM": load data are measured on OEM side + - "simulatedOEM": load data are simulated on OEM side + - "loggedSupplier": the data are collected during usage and provided on supplier side + - "measuredSupplier": load data are measured on supplier side + - "simulatedSupplier": load data are simulated on supplier side + - "otherOrigin": any other origin of load data, may be not even a load spectrum + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +#### 3.2.5 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#52-non-normative-references). + +This aspect model is written in BAMM 1.0.0 as a modeling language. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.2.6 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.2.7 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier: + +```text +urn:bamm:io.catenax.rul:1.0.0##RemainingUsefulLife +``` + +#### 3.2.8 FORMATS OF SEMANTIC MODEL + +##### 3.2.8.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + +The ttl file can be found here: + +[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.rul/1.0.0/RemainingUsefulLife.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.rul/1.0.0/RemainingUsefulLife.ttl) + +The open-source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, AASX for Asset Administration Shell Submodel +Template or a HTML documentation. + +##### 3.2.8.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.2.8.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#52-non-normative-references)\]. + +Note: As soon as the specification V3.0 of the Asset Administration Shell specification is available +an update will be provided. + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* +> +> *This section only applies if using the notification based API* + +### 4.1 ENDURANCE PREDICTOR API + +#### 4.1.1 PRECONDITIONS AND DEPENDENCIES + +The Endurance Predictor service was designed with interoperability in mind, thus the communication in both directions (input/input) fully supports the Catena-X Notification standard. These aspects are also covered by Catena-X ontologies. +For this purpose, in the behaviour_ontology, which is part of the Standard CX-0084:v1.2 is defined accordingly. + +The two APIs described support the implementation of the dynamic behavior (i.e., service) of components (e.g., engine, gearbox..) in a digital behavior twin. +As the process is asynchronous, there are two APIs for different types of participants in the network. + +1. API endpoint to be provided by a Service Provider providing a service to predict the expected lifetime of a product based on load spectra. +2. API endpoint to be provided by a Service Requester application or participant to receive the outcome of such an analysis in an asynchronous manner. + +It is a non-central API, which can be implemented for various components. It relies on a load spectrum as input in order to calculate and return the corresponding RUL value. +The basic idea for the functionality of this API has been derived from CX-0023:v1.2 Notification API. + +As already mentioned in the Introduction, this standard provides the specification of the HTTP REST API endpoint to request (with an according Load Spectrum as input) and +sending RUL value via the Catena X Dataspace. Without this API an interoperability between different application, with an aim to receive RUL data, is not given. + +#### 4.1.2 API SPECIFICATION + +##### 4.1.2.1 API ENDPOINTS AND RESOURCES + +The notification API MUST be implemented as specified in the [[openAPI](https://github.com/catenax-eV/product-standardization-prod/blob/main/standards/CX-0058-APIEndurancePredictor/1.0.0/src/Notification_Endurance_predictor.json)] documentation as stated here: + +• POST /api/v1/routine/notification + +In fact, it is OPTIONAL to implement the endpoint paths exactly as described above. The reason is that those endpoints are not called from any supply chain partner directly. +Rather, they are called from the Dataspace Connector or a similar IDSA compliant connector as part of its data assets. In that sense, it is just important to +implement endpoints that can process the defined request body and respond with the HTTP status codes and - if required - reply with the defined response body. + +The IDSA compliant data assets will act similar to a reverse proxy for the notification endpoints, therefore rather the data assets are of significance, which should be exposed towards Catena-X through the Data Offer Catalogues in the Dataspace Connector or any other IDSA Protocol compatible connector. + +##### 4.1.2.2 AVAILABLE DATA TYPES + +The API MUST use JSON as the payload transported. +The APIs payload consists of a general notification header and a use case specific content dictionary. +The request and response are linked by the unique notificationID. + +#### 4.1.2.3 NOTIFICATION REQUEST PAYLOAD STRUCTURE + +The main part of the content dictionary MUST follow the specification in section 3.1 "[Semantic Model: Classified Load Spectrum](#31-aspect-model-classifiedloadspectrum)" as the load spectrum itself is given as the main input towards the endurance predictor. + +```json +{ + "header": { + "notificationID": "notification-UUID", + "senderBPN": "BPNL0000000000", + "senderAddress": "https://abc.com", + "recipientAddress":"https://connector-xxxx/BPNL000000", + "recipientBPN": "BPNL0000000", + "severity": "MINOR", + "status": "SENT", + "targetDate": "target-date", + "timeStamp": "time-stamp", + "classification": "RemainingUsefulLifePredictor", + "respondAssetId": "urn:pilot:service:EndurancePredictorEstimationNotification" + }, + "content": { + "requestRefId": " notification-receipt ", + "endurancePredictorInputs": [ + { + "componentId": " notification-receipt ", + "classifiedLoadSpectrumGearOil": { + + }, + "classifiedLoadSpectrumGearSet": { + + } + } + ] + } +} +``` + +#### 4.1.2.4 NOTIFICATION RESPONSE PAYLOAD STRUCTURE + +The main part of the content dictionary MUST follow the specification in section 3.2 "[Semantic Model: Remaining Useful Life](#32-aspect-model-remainingusefullife)" as endurance predictor output MUST follow the semantics described in the corresponding model: + +```json +{ + "header": { + "referencedNotificationID": "notification-UUID", + "senderBPN": "BPNL0000000", + "senderAddress": "https://connector-xy.com/BPNL0000000", + "classification": "EndurancePredictorResult", + "recipientAddress": "https://connector-xx.com", + "recipientBPN": "BPNL0000000", + "severity": "MINOR", + "status": "SENT", + "targetDate": "target-date", + "timeStamp": "time-stamp", + "respondAssetId": "urn:pilot:service:EndurancePredictorEstimationNotification" + }, + "content": { + "componentType": "GearBox", + "endurancePredictorOutputs": [ + { + "componentType": "GearSet", + "componentId": " notification-receipt ", + "remainingUsefulLife": { + + } + } + ] + } + } +``` + +#### 4.1.2.5 NOTIFICATION RESPONSE ERROR PAYLOAD STRUCTURE + +```json +{ + "header": { + "referencedNotificationID": "notification-UUID", + "senderBPN": "BPNL0000000", + "senderAddress": "https://connector-xy.com/BPNL0000000", + "classification": "EndurancePredictorResult", + "recipientAddress": "https://connector-xx.com", + "recipientBPN": "BPNL0000000", + "severity": "MINOR", + "status": "SENT", + "targetDate": "target-date", + "timeStamp": "time-stamp", + "respondAssetId": "urn:pilot:service:EndurancePredictorEstimationNotification" + }, + "content": { + "componentType": "GearBox", + "type": "Error", + "message": "Error Message", + "endurancePredictorOutputs": [] + } + } +``` + +#### 4.1.3 EDC DATA ASSET STRUCTURE + +When using the Tractus-X EDC (Eclipse Dataspace Connector), the following asset MUST be registered by the specific roles in this process. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and +provisioning towards Catena-X. + +##### 4.1.3.1 SERVICE CONSUMER + +As an application provider or an data consumer calling an endurance predictor of another participant an API for asynchronous receival of the result is required. +The corresponding data asset **MUST** look like the following: + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#" + }, + "asset": { + "@type": "Asset", + "@id": "endurancePredictorResult-receipt", + "properties": { + "dct:type": { + "@id": "EndurancePredictorResult" + }, + "cx-common:name": "endurancePredictorResult-receipt", + "cx-common:description": "Asset to receive endurance predictor results.", + "cx-common:version": "1.0", + "cx-common:contenttype": "application/json" + } + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "https://{{httpServerWhichOffersTheHttpEndpoint}}/api/v1/routine/notification", + "proxyMethod": "true", + "proxyQueryParams": "true", + "proxyBody": "true" + } +} +``` + +The variable \{\{httpServerWhichOffersTheHttpEndpoint\}\} MUST be set to the HTTP server that offers the endpoint. The path /api/v1/routine/notification MAY align with the HTTP POST path as stated in 4.1.2.1. +In that sense it can change dependent on the endurance application. + +##### 4.1.3.2 SERVICE PROVIDER + +As an service provider or data provider providing an endpoint for an endurance predictor service, an API for receival of the request including the load spectrum data is required. +The corresponding data asset **MUST** look like the following: + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#" + }, + "asset": { + "@type": "Asset", + "@id": "endurancePredictorRequest-receipt", + "properties": { + "dct:type": { + "@id": "EndurancePredictorRequest" + }, + "cx-common:name": "endurancePredictorRequest-receipt", + "cx-common:description": "Asset to receive endurance predictor requests incl. load spectrum.", + "cx-common:version": "1.0", + "cx-common:contenttype": "application/json" + } + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "https://{{httpServerWhichOffersTheHttpEndpoint}}/api/v1/routine/notification", + "proxyMethod": "true", + "proxyQueryParams": "true", + "proxyBody": "true" + } +} +``` + +The variable \{\{httpServerWhichOffersTheHttpEndpoint\}\} MUST be set to the HTTP server that offers the endpoint. The path /api/v1/routine/notification MAY align with the HTTP POST path as stated in 4.1.2.1. +In that sense it can change dependent on the endurance application. + +#### 4.1.4 ERROR HANDLING + +The following http response codes MUST be defined for HTTP POST endpoint for the Endurance Predictor endpoint. + +| Code | Description | +|------|----------------------------------| +| 202 | Accepted | +| 400 | Request body was malformed | + +## 5 REFERENCES + +### 5.1 NORMATIVE REFERENCES + +- CX–0018:v3.0 Dataspace Connectivity +- CX-0023:v1.2 Notification API (only if using the notification based API) +- CX-0067:v1.1 Ontology Models to realize federated query in Catena-X (only if using the Knowledge Agent) +- CX-0084:v1.2 Federated Queries in Data Spaces (Knowledge Agent) + +### 5.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- [CX_Operating_Modelv2.1_final.pdf (catena-x.net)](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf) + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/assets/architecture_overview_knowledge_agent.drawio.png b/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/assets/architecture_overview_knowledge_agent.drawio.png new file mode 100644 index 000000000..048b99f21 Binary files /dev/null and b/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/assets/architecture_overview_knowledge_agent.drawio.png differ diff --git a/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/assets/architecture_overview_notification_based.drawio.png b/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/assets/architecture_overview_notification_based.drawio.png new file mode 100644 index 000000000..c266e1213 Binary files /dev/null and b/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/assets/architecture_overview_notification_based.drawio.png differ diff --git a/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/assets/remaing_useful_life.png b/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/assets/remaing_useful_life.png new file mode 100644 index 000000000..849b73f4d Binary files /dev/null and b/docs/standards/CX-0059-UseCaseBehaviourTwinEndurancePredictor/assets/remaing_useful_life.png differ diff --git a/docs/standards/CX-0065-TriangleForDismantlingService/CX-0065-TriangleForDismantlingService.md b/docs/standards/CX-0065-TriangleForDismantlingService/CX-0065-TriangleForDismantlingService.md new file mode 100644 index 000000000..97e5b3ab7 --- /dev/null +++ b/docs/standards/CX-0065-TriangleForDismantlingService/CX-0065-TriangleForDismantlingService.md @@ -0,0 +1,328 @@ +# CX-0065 Triangle for Dismantling Service v1.0.0 + +## ABSTRACT + +This standard focuses on the Dismantling use case. This includes relevant requirements for: + +- data provider, that want to provide data for dismantling through Catena-X, +- data consumer, that are searching for dismantling information such as R-Strategies in Catena-X and +- Application developer/provider supporting the provisioning and consuming of dismantling information. + +In this document, keywords for registering and searching dismantling information such as material information are defined as well as general call sequences to register or consume these information. In this document, the *standardization triangle* will be described, meaning the relevant architectural and data elements for working with the use case. + +## 1. INTRODUCTION + +This document defines the so-called *standardization triangle* for the dismantling use case. Standardization triangle hereby means the mandatory components, data models, APIs etc. that are required to enable the dismantling use case. Additionally, search objects as well as procedures to registering/providing and consuming the data will be defined. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This document is meant for the following roles: + +- Data Provider / Consumer +- Business Application Provider +- Onboarding Service Provider +- Consulting Services Provider + +### 1.2 CONTEXT + +> *This section is non-normative* + +At a vehicle's end of life (EoL), it is usually dismantled by a certified dismantler. This means, that the components and materials are evaluated and often are removed and sold or forwarded as material. + +The decision, what should be done with the vehicle and its components is called R-Strategy (e.g. Repair, Reuse, Recycle, ...). The decision on the relevant R-Strategies can be prior to the actual dismantling, as it influences if a component shall be bought or not. + +This standard defines relevant communication within Catena-X to support dismantling decisions. + +### 1.3 ARCHITECTURE OVERVIEW + +> *This section is non-normative* + +General architectural sequences can be seen in the Annex ([FIGURES](#figures)). Mandatory components are: + +- Eclipse Data Space Connector (EDC) or equivalent components in compliance with the standard 0018 Eclipse Data Space Connector (EDC) +- Usage of digital twin registry to provide twins of the vehicles with respective BOMs and dismantling information +- connections to components for authenticate as a data provider or consumer, such as the Catena-X portal, DAPS and similar platforms. + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they are conform with the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To proof conformity with the use case dismantling standard as a data consumer or app provider demonstrate that you + +- can find digital twins of a vehicle through a VAN, +- can find components of the vehicle such as batteries, +- can visualize relevant submodels such as materials. + +To proof conformity with the use case dismantling standard as data provider show that you + +- are conform with the provisioning conditions in [ADDITIONAL REQUIREMENTS](#22-additional-requirements). + +### 1.6 EXAMPLES + +No Example provided. + +### 1.7 TERMINOLOGY + +> *This section is non-normative* + +The following terms are especially relevant for the understanding of the standard: + +- Asset Administration Shell (AAS): The AAS is chosen standard in Catena-X to define Digital Twins of an asset (e.g. a battery or a full vehicle). +- Business Partner Number (BPN): A BPN is the unique identifier of a partner within Catena-X. +- Vehicle Identification Number (VIN): (In German "Fahrgestellnummer") Identification of an instance of a vehicle. +- Vehicle Anonymised Number (VAN): As the VIN can be traced back to a person and thus is GDPR relevant. Therefore, the VAN has been introduced in Catena-X to avoid person related data in requests. This number wil be used to register and search digital twins. + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2. STANDARDS FOR "USECASE DISMANTLING" + +> *This section is normative* + +### 2.1 LIST OF STANDALONE STANDARDS + +> *This section is normative* + +To participate in the dismantling use-case, the following single standards MUST be fulfilled by all participants for which the standard is relevant: + +- CX - 0002 Digital Twins in Catena - X +- CX - 0015 IAM & Access Control Paradigm +- CX - 0018 Eclipse Data Space Connector (EDC) + +### 2.2 ADDITIONAL REQUIREMENTS + +A participant of the dismantling use case MUST sign the overall terms and conditions (Catena-X) and the dismantling terms and conditions. + +A data provider MUST register their AAS of the vehicle with a ``van`` for example: + +```json +{ + "description": [ + { + "language": "en", + "text": "The shell for a vehicle" + } + ], + "globalAssetId": { + "value": [ + "{globalAssetId}" + ] + }, + "idShort": "vehicle", + "identification": "...", + "specificAssetIds": [ + { + "key": "van", + "value": "X123456789012X12345678901234566" // = VAN + }, + ... + ] +} +``` + +EDC-assets of data providers MUST follow the following structure: + +```json +{ + "asset": { + "properties": { + "asset:prop:id": "{{AssetId}}", + "asset:prop:description": "{{Description}}" + } + }, + "dataAddress": { + "properties": { + "type": "HttpData", + "baseUrl": "{{DataProviderEndpointUrl}}/{{DigitalTwinId}}-{{DigitalTwinSubmodelId}}" + } + } +} +``` + +contract Definitions of data providers MUST follow this structure: + +```json +{ + "id": "{{ContractDefinitionId}}", + "criteria": [ + { + "operandLeft": "asset:prop:id", + "operator": "=", + "operandRight": "{{AssetId}}" + } + ], + "accessPolicyId": "{{AccessPolicyId}}", + "contractPolicyId": "{{ContractPolicyId}}" +} +``` + +Data consumer SHOULD request data assets through the key-value pair ``"van"`` = ``partInstanceId``. A procedure is documented in [Fig. 1: Identify digital twin](#figures). + +```json +{ + "key": "van", + "value": "X123456789012X12345678901234566" +} +``` + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +Currently used data model standards: + +- [CX-0066-EndofLifeofVehicleCompliance](https://catena-x.net/de/standard-library) +- [CX-0031-DataModelMaterialForHomologation](https://catena-x.net/de/standard-library) + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +A logic to calculate an R-Strategy can be found in the paper [Mügge, J.; Hahn, I. R.; Riedelsheimer, T. and Chatzis, J.: "Digital Twins for Circular Economy Enabling Decision Support for R-Strategies"](https://www.industrie-management.de/sites/industrie-management.de/files/img-digitalisierung/IM-06-2022_Mugge.pdf). + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +There is yet no publicly available reference implementation for dismantling support + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +```plantuml +@startuml +Title +Fig. 1: Identify digital twin +end title +actor User + +box "Data Consumer Environment" +participant "Dismantling consumer application" as App +end box + +participant "Digital Twin Registry" as DTR + +box "Data Provider" +participant "VIN/VAN Converter" as VVDec +end box + +alt VIN +User -> App: insert VIN +App -> DTR: Lookup company Endpoints of VIN-VAN-converter for VIN +App <--DTR: Return VIN-VAN-Converter Endpoint +App -> VVDec: Convert VIN to VAN +App <--DTR: VAN for inserted VIN +else VAN already known +User-> App: insert VAN +end + +App-> DTR: Request digital twins with VAN +note left +Method: GET +Path: /lookup/shells +Parameters: The key-value-pair of the vehicle +- ( key: "van", value : specific van) +end note +App<--DTR: UUID/aasIdentifier of vehicle(s) matching the key-value pair +User<--App: List of digital twin identifier +@enduml +``` + +```plantuml +@startuml +Title +Fig. 2: request CE aspects +end title +'Layout + +Actor "User" as VP + +box "Data Consumer" +participant "Dismantling +Application" as DD +'participant "AAS-Wrapper" as Wrapper +participant "Consumer EDC" as EDCC +'participant IRS as IRS +end box + +participant "Digital Twin Registry" as DTR + +box "Data Provider" +participant "VIN/VAN Converter" as VVDec +'participant "Submodel +Server" as SS +participant "Provider EDC" as EDCP +end box + +'Communication +skinparam SequenceMessageAlignment center +'skinparam SequenceLifeLineBackgroundColor #Red + +'activate DD +note over VP +The UUID/aasIdentifier can either be +from the previous step in the app +or inserted by the user. +end note +opt +VP -> DD:insert VAN or UUID +end + +DD -> DTR: Search for aspect and EDC-Endpoints in Digital Twin registry +note left +Method: GET +Path: registry/shell-descriptors/{aasIdentifier}/submodel-descriptors +Parameters: the aasIdentifier from the twin lookup +- ( aasIdentifier: UUID of AAS) +end note +DD<--DTR: return all submodel endpoints +DD->DD: Filter for relevant submodels +loop for all relevant submodels +DD->EDCC: request data from endpoint +EDCC->EDCP: Request data from endpoint +note left +This step includes a complex contract negotiation +between the EDCs and might involve further components +such as an AAS Wrapper, which is skipped in this diagram +as well as communication with the actual submodel server +end note +EDCC<--EDCP: Return requested data +DD<--EDCC: return requested data +end +VP<--DD: visualize dismantling information + + +@enduml + +``` + +### TABLES + +> *This section is non-normative* + +*Table 1: relevant usage policies* + +| Identifier | Description | +|------------|-------------| +| R3\_ReadDisplay | The data provided in the circular economy use case as well as by and for related business applications such as Batterypass application, Marketplace, Circularity Cockpit and R-Strategy Assistant shall only be displayed to the data user and read by applications for circular economy usages such as R-Strategy logic calculations or support of buying decisions by the data user. The end-user confirms that the data is not used for analytic purposes out side the circular economy scope such as analyzing consumer behavior based on load cycles or analyzing the number of produced cars or components by a company. It also not allowed to print the data or distributed it to third parties. | +| R3\_ExchangeOfAnonymousData | The data exchanged in the use case is focused on non-personal related data. Therefore, data provider confirm, that they only provide anonymized data to data consumers or that the data is anonymized in the data transfer. | +| R3\_ExchangePartner | Data is only exchanged between partners, that have signed a bilateral contract to exchange the data. Therefore, data consumers are only allowed to consume data once their legal entity has signed a respective contract. | + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0066-AspectModelEndofLifeofVehicleCompliance/CX-0066-AspectModelEndofLifeofVehicleCompliance.md b/docs/standards/CX-0066-AspectModelEndofLifeofVehicleCompliance/CX-0066-AspectModelEndofLifeofVehicleCompliance.md new file mode 100644 index 000000000..c7f7cfb6c --- /dev/null +++ b/docs/standards/CX-0066-AspectModelEndofLifeofVehicleCompliance/CX-0066-AspectModelEndofLifeofVehicleCompliance.md @@ -0,0 +1,607 @@ + +# CX-0066 Aspect Model: End of Life of Vehicle Compliance v1.0.0 + +## ABSTRACT + +The data model End of Life of Vehicle Compliance describes the RRR calculation results according to [ISO 22628](#31-normative-references). The values represent the calculated quotas, the material masses of each fraction, the mass of the vehicle or component, the considered recycling technologies, and the list of potential dismantled parts. + +## 1. INTRODUCTION + +This document describes one semantic model used in the Catena-X network + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +The standard is relevant for the following roles: + +- Data Provider / Consumer +- Business Application Provider +- Enablement Service Provider + +### 1.2 CONTEXT + +> *This section is non-normative* + +The data model End of Life of Vehicle Compliance describes the RRR calculation results according to [ISO 22628](#31-normative-references). The values represent the calculated quotas, the material masses of each fraction, the mass of the vehicle or component, the considered recycling technologies and the list of potential dismantled parts. + +### 1.3 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, +examples, and notes in this specification are non-normative. Everything else in +this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, +**REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be +interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they +appear in all capitals, as shown here. + +### 1.4 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to prove, that they are conform +with the Catena-X standards. To validate that the standards are applied +correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +- To proof conformity with the EndofLifeofVehicleCompliance Semantic Model Standard check your json file against the json schema. + +- Every data provider of EndofLifeofVehicleCompliance data MUST provide the data conformant to the semantic model specified in this document. + +- The unique identifier of the semantic model specified in this document MUST be used by the data provider to define the semantics of the data being transferred. + +- Every certified business application relying on EndofLifeofVehicleCompliance data MUST be able to consume data conformant to the semantic model specified in this document. + +- This semantic model MUST be made available in the central Semantic Hub. + +The proof of conformity for a single semantic model is done according to the general rules for proving the conformity of data provided to a semantic model or the ability to consume the corresponding data. + +### 1.5 EXAMPLES + +```json +{"endOfLifeofVehicleCompliance":[{ + "remainingTotalMassRecyclableMaterial":355.88, + "brandName":"VW", + "totalMassPretreatment":555.98, + "dismantledMass":{"tyres":44.88, + "batteries":21.85, + "oilFilters":5.78, + "dismantledFluids":22.58, + "catalyticConverters":22.88, + "lpgTanks":45.78,"cngTanks":55.78}, + "documentation":"Report.pdf", + "totalMassDismantling":555.77, + "dismantledParts":{"itemNumber":"222.555ab", + "additionalItemName":"Rear light", + "itemName":"Dashboard", + "itemMass":33.88}, + "remainingVehicleMetallicContent":555.88, + "remainingTotalMassEnergyRecovery":55.78, + "recoverabilityRate":95, + "vehicleMass":2876.12, + "materials":{"glass":111.55,"elastomers":222.55, + "metals":2876.12, + "modifiedOrganicNaturalMaterials":33.45, + "polymers":300.77, + "others":444.47, + "fluids":44.87}, + "recyclingTechnology":{"technologyName":"Selective dissolving of plastics", + "massRecycledByTechnology":553.55, + "technologyNumber":"2"}, + "model":"E-class", + "recyclabilityRate":90 +}] +} +``` + +### 1.6 TERMINOLOGY + +> *This section is non-normative* + +- **brandName:** +The brand name under the vehicle has been marketed, brand name used by the OEM. + +- **model:** +The model name of the vehicle. + +- **totalMassPretreatment:** +The total mass of all components of a vehicle that are related to the pre-treatment. + +- **dismantledMass:** +The total mass of all components of a vehicle that have been dismantled for the purpose of material reuse or material recycling. + +- **batteries:** +The mass of all batteries of a vehicle. + +- **oilFilters:** +The mass of all oil filters of a vehicle. + +- **dismantledFluids:** +The mass of all drained fluids of a vehicle. + +- **catalyticConverters:** +The mass of all catalytic converters and exhaust system filters of a vehicle. + +- **lpgTanks:** +The mass of all LPG tanks a vehicle. + +- **cngTanks:** +The mass of all CNG tanks a vehicle. + +- **documentation:** +The file name of the report as .pdf. + +- **totalMassDismantling:** +The total mass of all components of a vehicle that have been dismantled for the purpose of material reuse or material recycling and the total mass of all pre-treatment activities. + +- **dismantledParts:** +The list of parts that have been dismantled. + +- **additionalItemName:** +The additional information of a dismantled part like position or reference + +- **itemName:** +The name of a dismantled part + +- **itemMass:** +The mass of each individual dismantled part. + +- **remainingVehicleMetallicContent:** +The metal content that has not been dismantled. + +- **remainingTotalMassEnergyRecovery:** +The mass of material that is dedicated to energy recovery. + +- **recoverabilityRate:** +The Recovery rate in % + +- **recyclabilityRate:** +The Reuse and recycling rate in % + +- **vehicleMass:** +The empty mass of a vehicle in operative conditions. + +- **Materials:** +Material fractions + +- **Glass:** +The mass of the glass fraction. + +- **elastomers:** +The mass of the elastomer fraction. + +- **metals:** +The mass of the metal fraction. + +- **modifiedOrganicNaturalMaterials:** +The mass of the MON fraction. + +- **polymers:** +The mass of the polymer fraction. + +- **others:** +The mass of the others fraction. + +- **fluids:** +The mass of the fluids fraction. + +- **recyclingTechnology:** +Technologies considered at the calculations. + +- **technologyName:** +Name of the considered technology + +- **massRecycledByTechnology:** +Mass treated by the considered technology + +Additional terminology used in this standard can be looked up in the glossary on +the association homepage. + +Aspect Model +: a formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect. + +: Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model. + +: Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +*[Source: Catena-X, CX-0002, note 3 removed]* + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 ASPECT MODEL “ENDOFLIFEOFVEHICLECOMPLIANCE” + +### 2.1 INTRODUCTION + +The data model End of Life of Vehicle Compliance describes the RRR calculation results according to [ISO 22628](#31-normative-references). The values represent the calculated quotas, the material masses of each fraction, the mass of the vehicle or component, the considered recycling technologies and the list of potential dismantled parts + +### 2.2 SPECIFICATION ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#32-non-normative-references). + +This aspect model is written in SAMM 2.0.0 as a modeling language conformant to CX-0003 +as input for the semantic deriven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +### 2.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group R-Strategy Assistant. +This Catena-X data model is made available under the terms of the Creative Commons Attribution +4.0 International (CC-BY-4.0) license, which is available at Creative Commons4F4F. + +### 2.4 IDENTIFER OF SEMANTIC MODEL + +The semantic model has the unique identifier: + +```text + urn:bamm:io.catenax.end_of_life_of_vehicle_compliance:1.0.0 +``` + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +### 2.5 FORMATS OF SEMANTIC MODEL + +#### 2.5.1 RDF Turtle + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + +```text +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.material_for_homologation/1.0.0/MaterialForHomologation.ttl + +``` + +Please note that the linked version contains the semantic model’s latest version at the time of publication of this standard. However, it is possible that minor functional adjustments (noticeable by increments of the middle number of the version number: 1.0.0) or bug fixes - downward compatible - (noticeable by increments of the last number of the version number: 1.0.X) have been added in the meantime. Such updated or adjusted versions are not explicitly linked, as they do not require a new standardization document and were not available at the time of the publication of this standard. Accordingly, it is recommended to look for the updated semantic model in eclipse-tractusx/sldt-semantic-models repository and to use the updated version instead, as it brings important bug fixes or even additional functionalities. + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +#### 2.5.2 JSON Schema + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +```json + +{ + "$schema": "http://json-schema.org/draft-04/schema", + "description": "Model to depict the list of materials, parts and recycling rates and technologies of a given vehicle at the end of its life.", + "type": "object", + "components": { + "schemas": { + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_BrandNameCharacteristic": { + "type": "string", + "description": "Characteristic to describe the manufacturer name." + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_ModelCharacteristic": { + "type": "string", + "description": "Characteristic to describe the commercial name of the car type." + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_VehicleMassCharacteristic": { + "type": "number", + "description": "Characteristic to describe the empty mass of the operational vehicle." + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic": { + "type": "number", + "description": "Characteristic to describe the mass of materials and parts." + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MaterialsCharacteristic": { + "description": "Characteristic to describe the materials breakdown.", + "type": "object", + "properties": { + "metals": { + "description": "Share of metals in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "polymers": { + "description": "Share of polymers in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "elastomers": { + "description": "Share of elastomers in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "glass": { + "description": "Share of glass in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "fluids": { + "description": "Share of fluids in kg. E.g. fuel tank filled at least 90%.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "modifiedOrganicNaturalMaterials": { + "description": "Share of modified organic natural materials (MONM), such as leather, in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "others": { + "description": "Share of others in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + } + }, + "required": [ + "metals", + "polymers", + "elastomers", + "glass", + "fluids", + "modifiedOrganicNaturalMaterials", + "others" + ] + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_DismantledMassCharacteristic":{ + "description": "Characteristic to describe the mass of dismantled components.", + "type": "object", + "properties": { + "dismantledFluids": { + "description": "Mass of dismantled fluids in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "batteries": { + "description": "Mass of dismantled batteries in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "oilFilters": { + "description": "Mass of dismantled oil filters in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "lpgTanks": { + "description": "Mass of dismantled LPG tanks in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "cngTanks": { + "description": "Mass of dismantled CNG tanks in kg", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "tyres": { + "description": "Mass of dismantled tyres in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "catalyticConverters": { + "description": "Mass of dismantled catalytic converters in kg.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + } + }, + "required": [ + "dismantledFluids", + "batteries", + "oilFilters", + "lpgTanks", + "cngTanks", + "tyres", + "catalyticConverters" + ] + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_ItemNumberCharacteristic": { + "type": "string", + "description": "Characteristic to describe the item number of the dismantled part." + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_ItemNameCharacteristic": { + "type": "string", + "description": "Characteristic to describe the item name of the dismantled part." + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_DismantledPartsCharacteristic": { + "description": "Characteristic to describe the list of dismantled parts.", + "type": "object", + "properties": { + "itemNumber": { + "description": "Item number of the dismantled part.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_ItemNumberCharacteristic" + }, + "itemName": { + "description": "Name of the dismantled part.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_ItemNameCharacteristic" + }, + "itemMass": { + "description": "Mass of the dismantled part.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "additionalItemName": { + "description": "Item name of the dismantled parts which are attached in addition.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_ItemNameCharacteristic" + } + }, + "required": [ + "itemNumber", + "itemName", + "itemMass", + "additionalItemName" + ] + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_DocumentationCharacteristic": { + "type": "string", + "description": "Characteristic to describe a report document in pdf format." + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_RecyclabilityRateCharacteristic": { + "type": "number", + "description": "Characteristic to represent the recyclability rate." + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_RecoverabilityRateCharacteristic": { + "type": "number", + "description": "Characteristic to describe the recoverability rate." + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_TechnologyNumberCharacteristic": { + "type": "string", + "description": "Characteristic to describe the list of numbers of the used recycling technologies within the type." + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_TechnologyNameCharacteristic": { + "type": "string", + "description": "Characteristic to describe the name of the used recycling technology." + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_RecyclingTechnologyCharacteristic": { + "description": "Characteristic to describe the used recycling technologies within the type.", + "type": "object", + "properties": { + "technologyNumber": { + "description": "List of numbers of the used recycling technologies within the type.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_TechnologyNumberCharacteristic" + }, + "technologyName": { + "description": "Name of the used recycling technology.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_TechnologyNameCharacteristic" + }, + "massRecycledByTechnology": { + "description": "Mass which is recycled by the listed recycling technology", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + } + }, + "required": [ + "technologyNumber", + "technologyName", + "massRecycledByTechnology" + ] + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_EndOfLifeComplianceEntity": { + "description": "Entity that represents the list of materials, parts and recycling rates and technologies of a given vehicle at the end of its life.", + "type": "object", + "properties": { + "brandName": { + "description": "Manufacturer name.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_BrandNameCharacteristic" + }, + "model": { + "description": "Comercial name of the car type.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_ModelCharacteristic" + }, + "vehicleMass": { + "description": "Empty mass of the operational vehicle.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_VehicleMassCharacteristic" + }, + "materials": { + "description": "Materials breakdown.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MaterialsCharacteristic" + }, + "dismantledMass": { + "description": "Mass of dismantled components.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_DismantledMassCharacteristic" + }, + "dismantledParts": { + "description": "List of dismantled parts.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_DismantledPartsCharacteristic" + }, + "totalMassPretreatment": { + "description": "Total mass of pretreatment.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "documentation": { + "description": "A report document in pdf format as attachment.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_DocumentationCharacteristic" + }, + "recyclabilityRate": { + "description": "Recyclability rate.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_RecyclabilityRateCharacteristic" + }, + "recoverabilityRate": { + "description": "Recoverability rate.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_RecoverabilityRateCharacteristic" + }, + "remainingTotalMassRecyclableMaterial": { + "description": "Remaining total mass of non-metallic residue treatment.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "remainingTotalMassEnergyRecovery": { + "description": "Remaining total mass of energy recoverable materials.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "totalMassDismantling": { + "description": "Total mass dismantling.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "remainingVehicleMetallicContent": { + "description": "Remaining vehicle metallic content.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_MassCharacteristic" + }, + "recyclingTechnology": { + "description": "List of the used recycling technologies.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_RecyclingTechnologyCharacteristic" + } + }, + "required": [ + "brandName", + "model", + "vehicleMass", + "materials", + "dismantledMass", + "dismantledParts", + "totalMassPretreatment", + "documentation", + "recyclabilityRate", + "recoverabilityRate", + "remainingTotalMassRecyclableMaterial", + "remainingTotalMassEnergyRecovery", + "totalMassDismantling", + "remainingVehicleMetallicContent", + "recyclingTechnology" + ] + }, + "urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_EndOfLifeOfVehicleComplianceCharacteristic": { + "description": "Characteristic to describe the list of materials, parts and recycling rates and technologies of a given vehicle at the end of its life.", + "type": "array", + "items": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_EndOfLifeComplianceEntity" + }, + "uniqueItems": true + } + } + }, + "properties": { + "endOfLifeofVehicleCompliance": { + "description": "Property that references the list of materials, parts and recycling rates and technologies of a given vehicle at the end of its life.", + "$ref": "#/components/schemas/urn_bamm_io.catenax.end_of_life_of_vehicle_compliance_1.0.0_EndOfLifeOfVehicleComplianceCharacteristic" + } + }, + "required": [ + "endOfLifeofVehicleCompliance" + ] +} +``` + +#### 2.5.3 aasx + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to [SMT](#32-non-normative-references). + +Note: As soon as the specification V3.0 of the Asset Administration Shell specfication is available +an update will be provided. + +### 2.6 SEMANTIC MODEL + +The data model is described in SAMM . A html documentation can be generated from the rdf turtle file. + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +CX-0003 SAMM Aspect Meta Model, Version 1.0.1 + +CX-0004 Governance Process for Semantic Models, Version 1.0.1 + +CX-0004 Governance Process for Semantic Models + +CX-0018 Eclipse Data Space Connector (EDC) + +CX-0001 EDC Discovery API, Version 1.1 + +ISO 22628 Road vehicles — Recyclability and recoverability — Calculation method: https://www.iso.org/standard/35061.html + +VDA 231-106 - https://webshop.vda.de/VDA/de/vda-231-106-102021 + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +[SMT] How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX.md b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX.md new file mode 100644 index 000000000..64baec4f9 --- /dev/null +++ b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX.md @@ -0,0 +1,692 @@ +# CX-0067 Ontology Models to realize federated query in Catena-X v1.1.0 + +## ABSTRACT + +This standard gives fundamental guidelines for the creation of ontology models to be used in Catena-X. It provides the semantic foundation for the so-called Knowledge Agent Approach that utilizes semantic web technologies for federated queries in data spaces (see Catena-X standard CX-0084). + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +- New subchapters [Digital Twin and Ontologies](#digital-twin-and-ontologies), [Taxonomy](#taxonomy), [Asset Content Description](#asset-content-description), [Modeling of the Functions](#modeling-of-the-functions) have been added. +- Text, images and code snippets have been modified to make them easier to understand. + +## 1. INTRODUCTION + +Semantics is the art and science of understanding the meaning of data. In the context of Catena-X, this topic has a significant importance in the sense that data providers and consumers need to have the same understanding of what data is to be exchanged (see also [FAIR Principles](https://www.go-fair.org/fair-principles)). In the knowledge agent approach, ontologies are used to describe the semantics of data. Ontologies are similar to data models or data schemas in which the semantics and structure of data are described. In addition, ontologies provide a high degree of semantic expressiveness, i.e. formal semantics. This means that there is a logical system behind the ontologies. This allows automatic inference on data like "p-123" is_a part & part is_a physical object => "p-123" is_a physical object. Such inference enables strong typing of data. In this way,the machine can understand the meaning of the vocabulary 'part', that it is a physical object and not a document part or a design model part. It could be that the same vocabularies are used for different things in different data models. The formal semantics of ontologies prevent such misunderstandings in data caused by synonymity or homonymity, etc. and lead to better collaboration and interoperability among data space participants. On the other hand, the ontology-based approach represents the underlying data in assets as a graph structure. This allows flexible querying of typed and linked data. + +In applying the ontology-based data modeling in Catena-X, the following fundamentals should be achieved: + +- Maximise Semantics +- Reduce Complexity +- Minimise Redundancy + +The goal of this standard is to ensure that ontology models are designed with the right quality and in a harmonized way that is compatible with the knowledge agent data processing mechanisms (CX-0084 V1.0.0-1.2.0). The ontology-based data modeling in the knowledge agent approach is explained in detail in section [MODELING CONCEPT](#modeling-concept). + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +In general, this standard applies to the usage of ontologies in Catena-X with a specific focus on the Knowledge Agents data processing pattern (CX-0084). Thus, this standard does not inhibit the usage of other data models, such as SAMM standard for other Catena-X data processing patterns (e.g. for Digital Twin/Asset Administration Shell approach). If any other applications of ontologies in Catena-X emerge or already existing external ontologies shall be included/linked for Catena-X application, this standard will be revised accordingly (if applicable). + +The following stakeholders are addressed in particular by this standard: + +- **Business Application Providers** that create/request specific models/ model extensions to make their application and or business logic work (relevant for certification if solutions are based on knowledge agent approach for data processing). + +- **Data Providers** that need to supply data and or functional logic based on given specification of an ontology model (not relevant for certification). + +- **Enablement Service Providers** that offer data integration solutions, e.g. for mapping of ontology models to corporate-internal data models (relevant for certification if solutions for knowledge agent approach are provided). + +- **Catena-X e.V.** will have a significant role of supervising ontology development (governance process for model development and respective quality criteria, not relevant for certification). + +Created ontology models can be utilized as semantic basis for the so called "knowledge agent" approach to exchange data across Catena-X participants. This standard will reference required external standards. Furthermore, it will provide modeling guidelines that extend/restrict given W3C standards to decrease complexity and to make sure that the models are designed in a unified way compatible with CX0084 (knowledge agent standard). + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +The knowledge agent approach uses the [Semantic Web standards](https://www.w3.org/2001/sw/wiki/Main_Page). The Semantic Web is the semantic extension of the Web. In the Web, the content of Web pages is exchanged in a document-based way (Web of Documents). This has the disadvantage that a direct access to a certain content of the documents is not possible. Therefore, a new concept was developed in which the contents of documents are decomposed into data and described by data models (Web of Data). At the same time, a query language was developed with which the desired content can be queried directly. In the Semantic Web, the data models are called ontologies, based on the philosophical meaning 'study of being', because the data on the Web is the digital representation of things in the real world. Semantic Web ontologies are formal languages in which data can be described unambiguously and without redundancy. This makes the ever-growing volumes of data on the web more manageable and usable to generate new knowledge. A good example is the [DBpedia project](https://www.dbpedia.org/), which makes Wikipedia content available as data. In recent years, Semantic Web standards have been increasingly used in enterprises to create enterprise-wide knowledge graphs to structure internal big data and make it queryable to create knowledge. This concept is extended in the Knowledge Agent standard (CX-0084) to realize data exchange across the Catena-X dataspace. + +Semantic Web Standards used in knowledge agent approach + +- [OWL 2 QL Profile](https://www.w3.org/TR/owl2-profiles/#OWL_2_QL) for modeling ontologies, +- [OWL 2 RL Profile](https://www.w3.org/TR/owl2-profiles/#OWL_2_QL) for modeling common dataspace assets, +- [SKOS](https://www.w3.org/2004/02/skos/) for vocabularies, +- [RML](https://rml.io/specs/rml/) & [R2RML](https://www.w3.org/TR/2012/REC-r2rml-20120927/) for mapping data source model to asset model to provide data in an asset, +- [SHACL](https://www.w3.org/TR/shacl/) for data quality check and for describing which data is available in the asset and in which form, +- [RDF](https://www.w3.org/TR/rdf12-concepts/) for description and exchange of graph data, +- [Turtle](https://www.w3.org/TR/turtle/) for persisting, +- [SPARQL](https://www.w3.org/TR/sparql11-query/) profiles for transferring logic and querying catalogues, data and functions. + +#### Modeling Concept + +This section explains the concept of ontology-based data modeling of the knowledge agent approach. Furthermore, it is shown how the query of distributed data in dataspaces works on the basis of this concept. + +##### **Modeling with Ontologies** + +In the Knowledge Agent approach, the data is modeled with the Semantic Web Ontology language [OWL](https://www.w3.org/TR/2012/REC-owl2-primer-20121211/). This enables object-oriented modeling of domains with classes, attributes and relationships. Object-oriented modeling allows the modeling of a domain from general to specific by creating subclasses. The first step is to define the main classes that describe the domain. In the case of Catena-X, five main classes were defined. + +- Activity: This class comprises actions that are intentionally performed by instances of the actor over the course of the product life cycle and result in state changes in physical and conceptual objects. +- Actor: This class comprises organization, device or people, either individually or in groups, who have the potential to perform intentional actions of kinds for which someone may be held responsible. +- Physical object: This class includes objects of a material nature, which are documentation units and have physical boundaries. +- Conceptual object: This class includes non-material products, human-produced data related to physical objects. The production of such information may have been supported by the use of technical tools. +- Place: The class Place is determined by reference to the position of objects such as buildings, cities, or special geographic markers. + +![concept.jpg](./assets/concept.jpg) + +#### **Activity-centred Modeling** + +A well-known approach is the activity-centered or event-based modeling. The [CIDOC CRM](https://www.cidoc-crm.org/) ontology provides this idea and the main classes based on this concept. In this approach the classes actor, place, physical object and conceptual object are connected through activities. Instead of assigning all information to the physical object. This distributed representation has several advantages: + +- The life cycles of products and documents are represented separately and clearly. +- The activities have a start and end date so that the data can be queried chronologically. +- The data can be viewed and queried from different perspectives. + - Identifies all actors (e.g. companies) involved in an activity (e.g. manufacturing). + - Identifies all activities performed on a physical object (vehicle). + - Finds all activities that have been performed at a place. + - Searches for all physical objects (e.g. material) used in an activity (e.g. manufacturing). + - Search for conceptual objects related to a physical object in an activity. + +![model.jpg](./assets/model.jpg) + +#### **Core and Domain Ontologies** + +The concept described above is the basic modeling pattern in Knowledge Agent. We call it the [core ontology](https://w3id.org/catenax/ontology/core). Based on this ontology, specific domain ontologies can be modeled. A domain ontology can be created based on subclasses (e.g. Manufacturing is SubClassOf Activity), subrelations (e.g. has Manufacturer is SubPropertyOf has Participant) and subattributes. The domain ontology has the same structure as the core ontology, but can be extended to include additional classes. The Knowledge Agent approach uses OWL 2 QL for modeling. This is a subset of OWL 2 Full. The reason for this is that it includes most of the main features of conceptual models such as UML class diagrams and ER diagrams. It also provides polynomial time inference for large data sets. + +Benefits of the basic modeling pattern: + +- Easy for domain experts to understand and create new domain ontologies. +- Data is represented in datasets using the same pattern. +- Data can be queried with general queries such as 'Get All Actors' or specific queries such as 'Get Manufacturer'. + +![domain.jpg](./assets/domain.jpg) + +#### **Data Serialization** + +In the ontology-based approach, the data is serialized in graph structure using the Resource Description Framework (see [RDF](https://www.w3.org/TR/rdf12-concepts/)). Each node, also called a resource, is uniquely identified by a [URI](https://www.w3.org/wiki/URI). The edges are called property in RDF Graph because each relation forms a [subject-predicate-object triple](https://www.w3.org/wiki/SubjectPredicateObject). The nodes can be linked to other nodes (so-called object property). The relations used are from the Domain Ontology. At the same time, nodes can be linked to literals (so-called datatype property). With the property rdf:type, the nodes can be instantiated with domain classes. + +![data.jpg](./assets/data.jpg) + +The RDF graphs are stored in [RDF databases](https://www.w3.org/wiki/LargeTripleStores) (so-called triple store) and can be serialized in various formats such as xml, json, ttl, etc. Different data sources such as relational databases, XML, JSON and CSV files can be mapped to RDF graphs using standardized languages such as RML and R2RML. Based on the mapping, the data can be transformed or virtualized. Virtualization allows the data to be processed as RDF graphs without transforming it and storing it in a different location. + +Serialization of data based on Turtle syntax: + +``` +@prefix rdf: . +@prefix rdfs: . +@prefix owl: . +@prefix cx-core: . +@prefix cx-vehicle: . +@prefix exp: . + +# Vehicle Ontology +cx-vehicle:Vehicle rdf:type owl:Class ; + rdfs:subClassOf cx-core:PhysicalObject. + +cx-vehicle:vehicleIdentificationNumber rdf:type owl:DatatypeProperty ; + rdfs:subPropertyOf cx-core:id ; + rdfs:domain cx-vehicle:Vehicle ; + rdfs:range xsd:string . + +# Sample instance +exp:vehicle_1 rdf:type cx-vehicle:Vehicle, cx-core:PhysicalObject; + cx-core:name "Goggomobile" + cx-core:id "ABCDEFG1HI2J34567". + cx-vehicle:vehicleIdentificationNumber "ABCDEFG1HI2J34567". + +``` + +#### Digital Twin and Ontologies + +A digital twin is a digital object in a defined digital platform, such as the Web, data spaces, etc., that represents a real-world object and is identifiable and discoverable based on a defined unique identification. In the knowledge agent approach, a digital twin is an existing instance of a class of a domain ontology. The domain ontologies describe what kind of real-world objects it represents. With the cx-core:id all instances are identifiable in the Catena-X data space. A shape graph for the data provider's asset describes which digital twins are published in its asset. This makes the digital twins discoverable. + +#### Taxonomy + +A taxonomy is a collection of terms and their meaning. The terms are structured in a hierarchical form, whereby the relationships become broader and narrower. Taxonomies can be seen as a dictionary that ensures the correct use of terms. Ontologies use the terms to describe a domain. Domain ontologies can grow very quickly and become confusing. Therefore, it is not recommended to define classes for all types of a domain in an ontology. Instead of defining new subclasses, the instances can be typed using terms from the taxonomy. For this purpose, a Catena-X taxonomy is created with SKOS, which can be extended based on the classes of the core ontology. For example, the class Vehicle in the Vehicle Ontology describes vehicles. A small car is a special type of vehicle for which there it is not necessary to create a separate class. Instead, the term can be included in the taxonomy and the instances can be specified from there. + +``` +@prefix dct: . +@prefix rdf: . +@prefix rdfs: . +@prefix cx-core: . +@prefix cx-vehicle: . +@prefix cx-taxo: . + +# Catena-X Taxonomy +cx-taxo:Thing a skos:Concept; + skos:prefLabel "Thing"@en . + + cx-taxo:PhysicalObject a skos:Concept ; + skos:broader cx-taxo:Thing ; + skos:narrower cx-taxo:PhysicalObject ; + skos:prefLabel "Physical Object"@en . + + cx-taxo:Vehicle a skos:Concept ; + skos:broader cx-taxo:PhysicalObject ; + skos:narrower cx-taxo:SmallCar ; + skos:prefLabel "Vehicle"@en . + + cx-taxo:SmallCar a skos:Concept ; + skos:broader cx-taxo:Vehicle ; + skos:prefLabel "Small Car"@en . + + + +# Instance Vehicle +exp:vehicle_1 rdf:type cx-vehicle:Vehicle; + dct:type cx-taxo:SmallCar. + +``` + +#### Asset Content Description + +The Common Ontology contains classes and properties to describe assets on a meta-level. The asset class describes the URL from which the SPRAQL endpoint can be reached, which ontology was used to describe the data, what form the data has based on SHACL, which business partner provides the asset, and so on. The descriptions are helpful for ordinary users and necessary for application configuration. + +``` + +@prefix rdf: . +@prefix rdfs: . +@prefix owl: . +@prefix cx-core: . +@prefix cx-vehicle: . +@prefix sh: . + +# Asset description +exp:asset_1 rdf:type cx-common:Asset; + cx-core:id "asset_1"; + dct:type cx-taxo:GraphAsset; + cx-common:name "Vehicle dataset"; + rdfs:isDefinedBy ; + cx-common:shapeGraph exp:vehicleShapeGraph; + cx-common:dataAddress exp:dataAddress_1 + +exp:dataAddress_1 rdf:type cx-common:DataAddress; + cx-common:baseUrl "http://provisioning-agent:8080/sparql"; + + +# Asset content description (exp:vehicleShapeGraph) +exp:VehicleShape a sh:NodeShape ; + sh:targetClass cx-vehicle:Vehicle ; + sh:property [ + sh:path cx-vehicle:vehicleIdentificationNumber ; + sh:pattern "[A-Z0-9]{17}"; + sh:minCount 1 ; + ] ; + sh:property [ + sh:path cx-core:name ; + sh:datatype xsd:string ; + sh:minCount 1 ; + ] . + +``` + +#### Modeling of the Functions + +In the Knowledge Agent approach, in addition to publishing static data, it is also possible to offer services that perform calculations. These services can be called as functions with parameters. The functions can be modeled using the ontology function. The function parameters are defined by the cx-fx:argument. The ontology also contains function configuration properties that are required to configure the service. + +``` + +@prefix rdf: . +@prefix rdfs: . +@prefix owl: . +@prefix cx-core: . +@prefix cx-vehicle: . +@prefix exp: . +@prefix sh: . + + +# Sample Function + +exp:GetModelYear rdf:type cx-fx:Function; + rdfs:comment "Returns the model year for a given vehicle identification number.". + +exp:vin rdf:type cx-fx:argument ; + rdfs:domain cx-fx:Function ; + rdfs:range xsd:string. + +exp:ModelYear rdf:type cx-fx:Result; + +``` + +Functions are defined in a similar way to data in SHACL. In addition, the **cx-sh:hasAsArgument** property can be used to define which data property is required for a function argument to execute the function. + +``` + +# Function Ontology + +exp:GetModelYearShape a sh:NodeShape ; + sh:targetClass exp:GetModelYear ; + sh:property [ + cx-sh:hasAsArgument cx-vehicle:vehicleIdentificationNumber; + sh:path exp:vin ; + sh:pattern "[A-Z0-9]{17}"; + sh:minCount 1 ; + ] . + +``` + +#### Data Query + +The RDF graphs can be accessed using the SPARQL query language via a SPARQL HTTP protocol. SPARQL allows the definition of complex instance relationships and the search for the defined patterns in the RDF graphs. + +General query example: Returns all physical objects and their name and activities. + +``` +PREFIX cx: +PREFIX rdf: +PREFIX exp: + +select ?activity ?physicalObject ?name +where { + ?activity rdf:type cx:Activity. + ?physicalObject rdf:type cx:PhysicalObject. + ?physicalObject cx:name ?name. + ?activity cx:refersToPhysicalObject ?physicalObject. +} + +``` + +Query result (for mime-type "text/csv"): + +| ?activity | ?physicalObject |?name| +| ----------- | ----------- | ----------- | +|exp:manufacturing_1|exp:vehicle_1|"Goggomobil"| + +The same result (for mime-type "application/sparql-results+json"): + +```json +{ + "head": { + "vars": [ + "activity", + "physicalObject", + "name" + ] + }, + "results": { + "bindings": [ + { + "activity": { + "type": "uri", + "value": "http://www.example.com#manufacturing_1" + }, + "physicalObject": { + "type": "uri", + "value": "http://www.example.com#vehicle_1" + }, + "name": { + "type": "literal", + "value": "Goggomobil" + } + } + ] + } +} + +``` + +
+ +Specific query example: Returns all vehicles and their name and manufacturing activities. + +``` + +PREFIX cx: +PREFIX rdf: +PREFIX exp: + +select ?activity ?physicalObject ?name +where { + ?activity rdf:type cx:Manufacturing. + ?physicalObject rdf:type cx:Vehicle. + ?physicalObject cx:name ?name. + ?activity cx:refersToPhysicalObject ?physicalObject. +} + +``` + +Query result is the same as the first one: + +| ?activity | ?physicalObject |?name| +| ----------- | ----------- | ----------- | +|exp:manufacturing_1|exp:vehicle_1|"Goggomobil"| + +#### Federated Query + +An important advantage of SPARQL is that multiple repositories can be accessed from a single query. This feature gives Catena-X the great advantage of being able to query distributed data in different assets at the same time. + +![example.jpg](./assets/example.jpg) + +Federated query example: Returns all vehicle names from the OEM asset and for the same vehicles the names of the diagnosis results from the service asset. + +``` + +PREFIX cx: +PREFIX rdf: + +select ?vehicleName ?vehicleVin ?diagnosisResultName +where { + + # OEM Asset +  SERVICE { + ?physicalObjectOEM rdf:type cx:Vehicle. +    ?physicalObjectOEM cx:vin ?vehicleVin. + + #Service Asset +    SERVICE { + ?physicalObjectService rdf:type cx:Vehicle. +      ?physicalObjectService cx:vin ?vehicleVin. + ?physicalObjectService cx:name ?vehicleName. + ?activity rdf:type cx:Diagnosis. + ?activity cx:refersToPhysicalObject ?physicalObjectService. +      ?activity cx:refersToConceptualObject ?conceptualObject. +      ?conceptualObject cx:name ?diagnosisResultName. + } +  } +} + +``` + +Federated Query result (for mime-type "text/csv"): + +| ?vehicleName | ?vehicleVin | ?diagnosisResultName | +| ----------- | ----------- | ----------- | +|"Goggomobil"| "ABCDEFG1HI2J34567" |"Cylinder misfire"| +|"Fliewatuut"| "0815" |"Rotor breakdown"| +|"Herby"| "4711" |"Low Oil Pressure"| + +#### Skill + +A Skill in the knowledge agent approach is any Data/Federated Query which + +- is parameterizable by a set of input variables +- is published in the dataspace as a contractible asset with a unique id +- maybe invoked either on consumer-side (by downloading the query test) or provider-side (by execution of the query) + +For example, above federated query could be invoked under the assetname `SkillAsset?supplier=ListDiagnosis` and the following input parameter set (using contenttype "application/sparql-results+json") + +```json + +{ + "head": { + "vars": [ + "vehicleVin" + ] + }, + "results": { + "bindings": [ + { + "vin": { + "type": "literal", + "value": "ABCDEFG1HI2J34567" + } + }, + { + "vin": { + "type": "literal", + "value": "4711" + } + } + ] + } +} + +``` + +Skill invocation result (for mime-type "text/csv"): + +| ?vehicleName | ?vehicleVin | ?diagnosisResultName | +| ----------- | ----------- | ----------- | +|"Goggomobil"| "ABCDEFG1HI2J34567" |"Cylinder misfire"| +|"Herbie"| "4711" |"Low Oil Pressure"| + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, +examples, and notes in this specification are non-normative. Everything else in +this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, +**REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be +interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they +appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is normative* + +The type of ontology model characterized in this standard provides the basis for federated query with Knowledge Agent approach. To check for conformity, enablement service providers MUST prove to CAB (Conformity Assessment Bodies) that their offered solutions are able to process ontology models specified by this standard. Processing in this context means, that it is shown how the service to be certified opens/imports an ontology file without errors. The ontology files to be used for this conformance test MUST be retrieved from the corresponding repository governed by Catena-X e.V. in [Ontology Hub](https://w3id.org/catenax). Data providers and business application providers do not need a certification against this standard by CAB. + +In addition to technical conformance of the file format, the content of models also needs to be reviewed to be compliant with this standard and overall federated query approach. This proof of conformity is done by Catena-X e.V and their given governance process for semantic modeling. The corresponding organization is still to be created by Catena-X e.V. (Technical Committee for Modeling - TC4M). Respective quality criteria are listed in section [MODELING GUIDELINES](#modeling-guidelines). Thus, CAB will not review model content. + +### 1.7 TERMINOLOGY + +> *This section is non-normative_ + +| Syntax | Description | +| ----------- | ----------- | +| Attribute| An attribute represents a characteristic of an entity/class/individual, e.g. foaf:Person foaf:name "Max". An attribute is called 'owl:DatatypeProperty' in OWL | +| Class| A class is a set of individuals with shared structure/properties, i.e. kinds of things | +|Data Mapping |A data mapping connects the logical data model (ontology) with the underlying external physical data model (RDB schema)| +|Instance |An instance is an object of a class | +|Knowledge graph (KG) |A knowledge graph is a graph-structured database where knowledge is represented in the ontology and instances. There are two types of KGs: RDF and Labeled Property Graphs| +|Literal |A literal represents a data value, i.e. an element with a data type (string or integer), e.g. foaf:Person foaf:name "Max"| +|Namespace|A namespace is the base URI: Example: http://www.w3.org/1999/02/22-rdf-syntax-ns# with the prefix rdf| +|Ontology|An OWL ontology is a semantic data model based on description logic that consists of classes, relations, attributes for a specific domain of interest/discourse| +|Relation |A relation represents how two individuals are connected/related, e.g. cx:Bob cx:knows cx:Tom. A relation is called 'owl:ObjectProperty' in OWL| +|Triple|A triple is statement consisting of subject-predicate-object that is defined by RDF| +|Uniform Resource Identifier (URI)|An URI is an unique identifier for a (web) resource| +|Use Case|A Use Case (description) is an excerpt/a composition of a set of domain ontologies. It lists consuming and providing roles as well as cardinality/existence constraints on classes, relations and attributes for a specific application| + +## 2 MAIN CONTENT + +> *This section is normative* + +### Modeling Guidelines + +To facilitate the modeling process, a joint knowledge acquisition workshop with stakeholders (data producers, consumers, subject matter experts) is helpful. This workshop should have the following objectives: + +- Specify the ontology domain and scope +- Collect the requirements, data sources +- Prevent misunderstanding and moderate the expectations +- Collect relevant classes, relations, attributes + +This section defines modeling guidelines that help develop compliant domain ontologies based on the Core Ontology. New ontologies or adaptation of existing ontologies are created upon request of Catena-X use cases. + +#### **Content Modeling Guidelines** + +This section provides guidelines for effectively developing useful and reusable ontologies. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDPriorityGuidelineDescription
G11SHOULDDefine business requirements - Who knows, produces, consumes the data?
- State the business questions and define Asset queries
- Define the source data needed for the asset
G12MUSTModel scope - Identify the specific classes, attributes, and relationships for source data from existing domain ontologies. If none exist, create a new ontology or extend existing domain ontologies
G13aMUSTCreate Domain Ontology - Import the core ontology and develop the domain ontology based on the modeling concept (1.2.1 MODELING CONCEPT)
- Define import dependency in ontologies
- Define turtle file name followed by 'ontology' in snake_case
- Specify title of ontology followed by 'Ontology' in title case with whitespaces (domain) + ' Ontology', e.g. 'Vehicle Ontology'
- Specify version, use three integers separated with two dots
- Specify author, full name(s) of main responsible(s) comma separated
- Specify contributor, full name(s) domain expert(s) comma separated
- Specify description, i.e. state business problem and business questions
G13bSHOULDCreate Domain Ontology - Use a short, unambiguous domain name so that everyone can easily understand the meaning
G14MUSTCreate Classes- Specify the (machine-readable) identifier in English
- Use only noun or a phrase of nouns
- Specify the (human-readable) name in English and German
- Specify the definition in English, only short sentence
- Don't create subclasses unless the subclass has a specific attribute or relation. In this case, use Catena-X taxonomy (or other taxonomies) to type instances with dct:type (see http://purl.org/dc/elements/1.1/type)
G15MUSTCreate Relations - Specify the (machine-readable) identifier in English
- Use a complete verb phrase (e.g. is part of, knows)
- Specify the (human-readable) name in English and German
- Specify the domain
- Specify the range
- Specify the definition in English, only short sentence
G16MUSTCreate Attributes - Specify the (machine-readable) identifier in English
- Use a noun or a phrase of nouns
- Use class name as specifier, if the attribute is specific to the class
- Specify the (human-readable) name in English and German
- Specify the domain
- Specify the range
- Specify the definition in English, only short sentence
G16MAYDefine Use Cases - Select Classes, Relations, Attributes based on their (machine-readable) identifier in English
- Declare consuming roles
- Declare providing roles
- Declare Policies
+ +#### Technical Modeling Guideline + +Technical modeling guidelines are necessary for the correct use of ontologies in assets. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDPriorityGuidelineDescription
G21MUSTOntology export - Export ontology from editor as turtle file: (domain) + '_ontology.ttl', e.g. 'vehicle_ontology.ttl'
G22MUSTResolve redundancies - All classes, relations, attributes are uniquely defined in an ontology
G23MUSTOntology consistency - Check for conflicts with ontology reasoner
G24SHOULDOntology quality - Scan your ontology with the Ontology Pitfall Scanner (see https://oops.linkeddata.es/)
G25MUSTOntology use - Merge domain ontologies if necessary for the assets
G26SHOULDUse Case - Check use case constraints for assets depending on role
G27MUSTAsset Content Description - Create a shape graph based on SHACL for all classes and properties used in the asset
+ +
+ +#### **Syntactical Modeling Guidelines** + +Syntactic modeling guidelines increase comprehensibility and enable unified modeling of ontologies. + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDPriorityGuidelineDescription
G31SHOULDGeneral & Language - Avoid bad naming, consider interpretation and context
- Make names more specific if it has more than one interpretation
- Try to name examples, since it supports in the semantics
- Use short, meaningful, unambiguous names
- Use both English and German names, since it improves the semantics
- Avoid omitting definitions or bad definitions
- Don't use vague terms, e.g. model, data, ...
- Use only US English terms and name British terms as synonyms, e.g. meter/metre
- Don't use acronyms and abbreviations
- Note: natural language exhibits ambiguity, inaccuracy, uncertainty, vagueness
G32MUSTIdentifiers/URIs- Use only alphanumeric characters [A-z0-9] (IRI/URI standard)
- Use PascalCase/UpperCamelCase for classes (RDF/OWL standard)
- Use camelCase/lowerCamelCase for relations and attributes (RDF/OWL standard)
- Use the naming convention table (see below)
G33MUSTNaming Conventions - Use only alphanumeric characters with whitespaces [A-z0-9 ] + Umlaute (ÄäÖöÜüß)
- Use title case with whitespaces for classes and attributes for better human-readability
- Use lower case with whitespaces for relations
- Use the naming convention table (see below)
+ +**Naming convention table for identifiers and names:** + +|convention|identifier|name_en|name_de| +| ----------- | ----------- | ----------- | ----------- | +|language|English|English|German| +|readability|machine-readable|human-readable|human-readable| +|terms|generic terms|business terms|business terms| +|character range|[A-z0-9]|[A-z0-9 -]|[A-z0-9 -ÄäÖöÜüß]| +|separator|none|whitespace|whitespace| +|class case|PascalCase|Title Case|Title Case| +|relation case|camelCase|lower case|lower case| +|attribute case|camelCase|Title Case|Title Case| +|acronyms|no|yes|yes| + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +- CX - 0084 Federated Queries in Data Spaces (V1.0.0 - V1.2.0) +- [Ontology Hub](https://w3id.org/catenax) +- [OWL 2 QL Profile](https://www.w3.org/TR/owl2-profiles/#OWL_2_QL) +- [SKOS](https://www.w3.org/2004/02/skos/) +- [RML](https://rml.io/specs/rml/) +- [R2RML](https://www.w3.org/TR/2012/REC-r2rml-20120927/) +- [SHACL](https://www.w3.org/TR/shacl/) +- [RDF](https://www.w3.org/TR/rdf12-concepts/) +- [Turtle](https://www.w3.org/TR/turtle/) +- [SPARQL](https://www.w3.org/TR/sparql11-query/) + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- [FAIR Principles](https://www.go-fair.org/fair-principles) +- [Semantic Web standards](https://www.w3.org/2001/sw/wiki/Main_Page) +- [DBpedia project](https://www.dbpedia.org/) +- [CIDOC CRM](https://www.cidoc-crm.org/) +- [Subject-predicate-object triple](https://www.w3.org/wiki/SubjectPredicateObject). +- [RDF databases](https://www.w3.org/wiki/LargeTripleStores) +- [URI](https://www.w3.org/wiki/URI) + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +- The [Knowledge Agents](https://eclipse-tractusx.github.io/docs-kits/category/agents-kit) presents reference implementation. + +- The [Ontology repository](https://github.com/eclipse-tractusx/knowledge-agents-ontology) and its redirection over https://w3id.org/catenax presents a reference implementation. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/concept.jpg b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/concept.jpg new file mode 100644 index 000000000..71ac2b6f8 Binary files /dev/null and b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/concept.jpg differ diff --git a/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/data.jpg b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/data.jpg new file mode 100644 index 000000000..9a7f832c8 Binary files /dev/null and b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/data.jpg differ diff --git a/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/domain.jpg b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/domain.jpg new file mode 100644 index 000000000..0ccdc0eb9 Binary files /dev/null and b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/domain.jpg differ diff --git a/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/example.jpg b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/example.jpg new file mode 100644 index 000000000..dfda9de70 Binary files /dev/null and b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/example.jpg differ diff --git a/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/model.jpg b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/model.jpg new file mode 100644 index 000000000..7dd5248ec Binary files /dev/null and b/docs/standards/CX-0067-OntologyModelsToRealizeFederatedQueryInCatenaX/assets/model.jpg differ diff --git a/docs/standards/CX-0071-TriangleQualityEarlyWarningFieldandRootCause/CX-0071-TriangleQualityEarlyWarningFieldandRootCause.md b/docs/standards/CX-0071-TriangleQualityEarlyWarningFieldandRootCause/CX-0071-TriangleQualityEarlyWarningFieldandRootCause.md new file mode 100644 index 000000000..7de86d99e --- /dev/null +++ b/docs/standards/CX-0071-TriangleQualityEarlyWarningFieldandRootCause/CX-0071-TriangleQualityEarlyWarningFieldandRootCause.md @@ -0,0 +1,155 @@ +# CX-0071 Triangle Quality Early Warning Field and Root Cause v2.0.0 + +## ABSTRACT + +The Catena-X use case "Quality" (QAX) provides the ability to detect +quality issues the earliest possible to start root cause analyses and/or to enable +an early warning feature for new quality topics. In subsequent steps, counter +measures can also be defined earlier and monitored. In sum, this reduces the +number of vehicles affected by quality issues and increases the availability of the +vehicle and built-in components. Catena-X use case "Quality" is powered +by Catena-X standard core components to share data from OEM and suppliers +based on data sharing agreements and usage policies. + +## 1. INTRODUCTION + +The Catena-X use case "Quality" (QAX) uses multiple data models to +exchange data between automotive manufacturer (OEM) and component supplier +(TIER1). Each of these data models can be supplied independently. +The QualityTask data model defines the root element for Catena-X-based quality +work. It describes the quality task and why two companies want to work +collaboratively on a quality topic. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +The standard is relevant for the following roles within the scope of the Use Case "Quality" + *Data Provider/Consumer + * Business Application Provider + +In scope: + +- Data sharing between OEM, Tier1 and Tier n +- Earliest possible detection of potential issues with products and vehicles in usage +- Understanding of the root cause of the detected issues to enable earliest possible counter measure implementation + +### 1.2 CONTEXT + +> *This section is non-normative* + +For all participants of the Use Case "Quality" it is necessary to provide and consume the data in accordance to the standardized semantic data models CX-0036 - CX-0041 and CX-0091, CX-0092 to ensure the defined interoperability requirement "free of choice application" to be able to use the established inhouse tool set for analysis. + +### 1.3 ARCHITECTURE OVERVIEW + +> *This section is non-normative* + +Catena-X use case "Quality" data flow: Data is exported from existing backend systems and mapped to Catena-X aspect models - see list of relevant Catena-X aspect models for use case "Quality" in section [2.1 LIST OF STANDALONE STANDARDS](#21-list-of-standalone-standards) +The so generated files are transferred between different Catena-X participants using Catena-X' Eclipse Dataspace Connector (EDC). + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they are conform with the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +Since this Triangle document describes a set of standards to be fulfilled, participants MUST fulfill all mentioned standards and the respective conformity assessment criteria in addition to the specific criteria mentioned in this document. + +The specific criteria described in this document are describing the usage of the central tools as well as common tools described in the linked standardization documents and therefore compliance should be checked with the tools provided for these components. + +### 1.6 EXAMPLES + +### 1.7 TERMINOLOGY + +> *This section is non-normative* + +Business Partner Number (BPN) +: A BPN is the unique identifier of a partner within Catena-x + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +Eclipse Dataspace Connector (EDC) +: The EDC is a reference implementation of a connector for IDSA conform sovereign data exchange + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2. STANDARDS FOR "Triangle Quality Early Warning Field and Root Cause" + +> *This section is normative* + +### 2.1 LIST OF STANDALONE STANDARDS + +> *This section is normative* + +In order to participate in the Catena-X use case "Quality - Early Warning Field" and "Quality - Root Cause analysis" the following single standards **MUST** be fulfilled by all participants: + +CX - 0018 Eclipse Data Connector(EDC) v2.0.0 + +As OEM data provider I **MUST** align to the following aspect models in the corresponding data exchange: + +CX-0036 Aspect Model: QualityTask +CX-0037 Aspect Model: Vehicle.ProductionData +CX-0038 Aspect Model: Fleet.DiagnosticData +CX-0039 Aspect Model: Fleet.ClaimData +CX-0091 Aspect Model: Fleet.Vehicles +CX-0092 Aspect Model: QualityTaskAttachment + +As Supplier data provider I **MUST** align to the following aspect models in the corresponding data exchange: + +CX-0036 Aspect Model: QualityTask +CX-0040-Aspect Model: PartAnalyses +CX-0041-Aspect Model: ManufacturedPartsQualityInformation +CX-0092 Aspect Model: QualityTaskAttachment + +- Data provisioning and consuming **MUST** be done according the standardized semantic data models. +- The data provider defines the data content that will be provided. Provided data assets are defined in data sharing agreements and/or data usage policies. + +As Business Application Provider I **MUST** support at least 2 aspect models (minimum standard): One from OEM data provider aspect model list and one from Supplier data provider aspect model list. + +### 2.2 ADDITIONAL REQUIREMENTS + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +CX - 0018 EclipseDataConnector(EDC) +CX - 0036 Aspect Model: QualityTask +CX - 0037 Aspect Model: Vehicle.ProductionData +CX - 0038 Aspect Model: Fleet.DiagnosticData +CX - 0039 Aspect Model: Fleet.ClaimData +CX - 0040-Aspect Model: PartAnalyses +CX - 0041-Aspect Model: ManufacturedPartsQualityInformation +CX - 0091 Aspect Model: Fleet.Vehicles +CX - 0092 Aspect Model: QualityTaskAttachment + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0074-BusinessPartnerGateAPI/CX-0074-BusinessPartnerGateAPI.md b/docs/standards/CX-0074-BusinessPartnerGateAPI/CX-0074-BusinessPartnerGateAPI.md new file mode 100644 index 000000000..c613b0f7e --- /dev/null +++ b/docs/standards/CX-0074-BusinessPartnerGateAPI/CX-0074-BusinessPartnerGateAPI.md @@ -0,0 +1,603 @@ +# CX-0074 Business Partner Data Gate API v3.0.0 + +## TABLE OF CONTENTS + +## FOR WHOM IS THE STANDARD DESIGNED + +This document is mainly targeted to technical individuals involved in integrating and developing against this API, as well as business individuals who are involved in compliance process of this API. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +| **Version** | **Publishing Date** | **Author** | **Description of Change** | +| ----------- | ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 1.0.0 | 2023-09-26 | | Initial version by Catena-X Association | +| 1.1.0 | 2024-01-10 | | Small additions to the terminology chapters: added roles “supplier” & “customer”; added ISO 6709 and WGS 84 for geographic coordinates; added generic business partner outlook; moved attribute “sharing process started at” from specific business partner entities to the sharing state entry (API was correct); linked OpenAPI document in release branch instead of main | +| 2.0.0 | 2024-03-22 | | Added business partner description and removed detailed legal entity, site and address descriptions from terminology chapter; removed business partner type from changelog entry and sharing state entry descriptions; added business partner endpoints and removed legal entity, site and address endpoints; added “house number supplement” attribute; added “is own company data” attribute to claim ownership; switched to the new document structure | +| 3.0.0 | 2024-06-07 | | Added footnote to indicate that the term "site main address" is subject to change; added the CX-0018 version; changed and added the detailed asset structure; added footnote to clarify role distribution; removed classification sub-object, to reintroduce it in a presumably new form in one of the next non-breaking versions of this standard; removed business partner state and introduced separate states at representation classes; added outlook for business partner relationship; removed "api/catena/" from the endpoint definitions; added data sovereignty chapters as additional requirements. | + +## ABSTRACT + +The Business Partner Data Management (BPDM) is a distributed service-based system, composed of a set of dedicated services, that simultaneously serve multiple stakeholders. It is based on a central data pool of business partners, which is consistent with the overall design principles of Catena-X. The main target is to create business partner data records (such as customer/supplier) with a high quality and currentness, to provide other processes with these data. This results in less rework and adjustment due to better master data quality which ultimately leads to an overall cost reduction for participating companies. Additionally, Value Added Services shall be offered to enrich those business partner data sets even further and give additional information or warnings about the business partners. Getting a 360° view on your business partners also helps with reducing costs and achieving process excellence because better decisions can be made. + +The Business Partner Gate allows any Catena-X member to share own business partner data as well as business partner data of its suppliers and customers with the Catena-X network so that cleansed and enriched business partner data records, so-called Golden Records, can be created and made available. It is a main component of the architecture framework at Catena-X, as it enables the Catena-X members to leverage accurate, complete, and consistent business partner data for Catena-X applications and shared services. + +The Business Partner Gate can be accessed via the standardized API described in this standard. + +## 1. INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following audience: + +- Core Service Provider +- Onboarding Service Provider +- Data Provider and Consumer + +This document focuses on the Business Partner Gate API (short: Gate API) that is part of the Business Partner Data Management (BPDM) described on the [BPDM Catena-X Website](https://catena-x.net/en/offers-standards/bpdm). It is relevant for core service providers who want to provide services for uploading and downloading business partner master data records with the aim of cleansing and enriching them and thus create a high-quality business partner data record (Golden Record), which is identified by the business partner number (BPN). It is also relevant for onboarding service providers, business application providers as well as data providers and consumers who want to use such services. + +Not in scope are the structure and logic of the business partner number itself and the mechanism on how the business partner number is issued. There is a separate standard for this: CX-0010 Business Partner Number 2.0.0. + +Not in scope is the overall Business Partner Data Pool with all Golden Records within Catena-X and the way of how the Golden Records can be retrieved. There is a separate standard for this: CX-0012 Business Partner Data Pool API 4.0.0. + +Not in scope are the requirements of cleansing and enriching the business partner data records with the aim to create a Golden Record. There is a separate standard for this: CX-0076 Golden Record End to End Requirements Standard 1.2.0. + +You can find the other standards in the standard library of Catena-X: https://catena-x.net/en/standard-library + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +The Gate API is a crucial core component in Catena-X and its platform capability BPDM because it contributes to the following functions: + +1. Data Consistency: The Gate API allows that data related to business partners can be collected from multiple sources and can be sent through the sharing process to correct, enrich and validate the data. This ultimately enables BPDM to create accurate, complete, and consistent business partner data records (Golden Records). This helps to reduce the risk of errors and inconsistencies in business partner data. +2. Data Sovereignty: The Gate API allows to upload and download business partner data in a data sovereign way, because each Catena-X member has its own area of business partner data in BPDM, where private data (like customer / supplier relationships) is only visible to the Catena-X member. +3. Data Governance: The Gate API is the basis for a data governance framework and helps to enforce data quality standards, such as data completeness, accuracy, and consistency. It allows to compare the uploaded business partner data records against the corrected and enriched ones and provides the Sharing Member with a proposal for taking over the changes into the local MDM systems. This helps to ensure that business partner data is of high quality and can be trusted for use in various business processes. +4. Interoperability: The Gate API provides an interoperable and standardized way of uploading and downloading business partner data, ensuring both Core Service Provider interchangeability and streamlined data accessibility for all consumers of the API. + +There is a reference implementation for the Gate API on GitHub. It is part of a Spring Boot Kotlin open-source software project under the hood of the Eclipse Foundation and follows the Apache 2.0 licenses. + +For the complete and up-to-date API setup refer to the following website: https://github.com/eclipse-tractusx/bpdm + +For an architecture overview refer to the ARC42 documentation: https://github.com/eclipse-tractusx/bpdm/tree/release/6.0.x/docs/arc42 + +To use the Gate API in the BPDM use case apart from this standard, the following other standards should be considered by all participants for which this standard is relevant: + +- CX-0018 Dataspace Connectivity 3.0.0 +- CX-0012 Business Partner Data Pool API 4.0.0 + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +If sections are marked as non-normative, all authoring guidelines, diagrams, examples, and notes in these sections are non-normative. Everything else in this specification is normative. + +The key words MAY, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) [[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119)] [[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174)] when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +When implementing the API defined in this standard, proof of conformity **MUST** be provided by the following deliverables: + +- An OpenAPI specification defining the relevant resources for this standard +- Examples of data assets + +## 1.4 EXAMPLES + +The following examples show business partners which are potentially shared using this API. + +### 1.4.1 EXAMPLE 1 + +A business partner having assigned a legal entity and its legal address. + +***Dr. Ing. h.c. F. Porsche Aktiengesellschaft, Porscheplatz 1, 70435 Stuttgart, Deutschland*** + +![Legal Address](./assets/LegalAddress.png) + +### 1.4.2 EXAMPLE 2 + +A business partner having assigned a legal entity and one of its additional addresses. + +***Dr. Ing. h.c. F. Porsche Aktiengesellschaft, Schwieberdinger Str. 130, 70435 Stuttgart, Deutschland*** + +![Additional Address without Site](./assets/AdditionalAddressWithoutSite.png) + +### 1.4.3 EXAMPLE 3 + +A business partner having assigned a legal entity, a site and its main address[^5], which is not the legal address. + +***Dr. Ing. h.c. F. Porsche Aktiengesellschaft, Porsche Zuffenhausen, Werk 2, Hauptpforte, Porschestraße 42, 70435 Stuttgart, Deutschland*** + +![Site Main Address](./assets/SiteMainAddress.png) + +### 1.4.4 EXAMPLE 4 + +A business partner having assigned a legal entity, a site and its main address[^5], which is also the legal address. + +***Schaeffler Group USA INC. Fort Mill 1, 308 Springhill Farm Rd, Fort Mill, SC 29715, USA*** + +![Legal and Site Main Address](./assets/LegalAndSiteMainAddress.png) + +### 1.4.5 EXAMPLE 5 + +A business partner having assigned a legal entity, a site and one of its addresses, which is neither the legal address nor the main address[^5] of that site. + +***Dr. Ing. h.c. F. Porsche Aktiengesellschaft, Porsche Zuffenhausen, Werk 2, Pforte (Lieferanten), Schwieberdinger Str. 130, 70435 Stuttgart, Deutschland*** + +![Additional Address with Site](./assets/AdditionalAddressWithSite.png) + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +### 1.5.1 GENERAL + +**Golden Record:** Golden Record defines a business partner data record which successfully passed a set of predefined quality rules. These rules qualified the data record into a harmonized, standardized, and semantically unified data structure which is defined by Catena-X. The Golden Record status is a prerequisite for each BP data record to receive a valid BPN. + +**Sharing Member:** A Sharing Member is a Catena-X member who shares the business partner data of his own business environment[^6]. + +**Company Data:** Company Data are business partner data that represent the organizational structures of the Sharing Member. + +### 1.5.2 DATA MODEL + +This chapter explains the data model[^1] from a conceptual / terminology point of view. It does not include technical details of the API data model, such as: + +- differences in response and request +- differences in data stages (like input or output) +- attributes for pagination +- singular query parameters, which are not already attributes of the entities + +**Note that cardinalities always refer to the entity state as required output of the sharing process. In general, cardinalities of relations and attributes are not to be enforced while uploading business partners, except for the external ID.** + +#### 1.5.2.1 BUSINESS PARTNER + +![Business Partner](./assets/BusinessPartner.png) + +In general, a business partner is any entity (such as a customer, a supplier, an employee, or a service provider) that does business with another entity. + +In Catena-X, a business partner is an organization (such as an enterprise or company, university, association, etc., and not a natural person) or one of its substructures that acts as unique partner within the automotive supply chain - either in the role of a direct participant, or a consultant, or a non-production-material (NPM) supplier. + +The business partner entity in the Gate API provides a merged view on the entity combinations from the Business Partner Data Pool. In all combinations, a business partner has exactly one legal entity and one address assigned. It may additionally have a site assigned if the assigned address belongs to the site and the site is known to BPDM / has been shared by the owner. Note that for the assignment of the entities the respective BPNL, BPNS or BPNA (from the Business Partner Data Pool) are used. + +The business partner address type and the BPN assignment determine the entity combinations, on which the business partner entity provides a merged view. The combinations are visualized in the following table. All other combinations are invalid as output of the sharing process and will result in a [sharing error](#1528-sharing-state-entry): + +| **Description** | **Address Type** | **BPNL** | **BPNS** | **BPNA** | **Shared by** | **Example** | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------- | -------- | -------- | ------------- | --------------------------------- | +| A business partner having assigned a legal entity and its legal address. | Legal Address | has a | - | has a | Anyone | [1.4.1 EXAMPLE 1](#141-example-1) | +| A business partner having assigned a legal entity and one of its additional addresses. | Additional Address | has a | - | has a | Anyone | [1.4.2 EXAMPLE 2](#142-example-2) | +| A business partner having assigned a legal entity, a site and its main address[^5], which is not the legal address. | Site Main Address[^5] | has a | has a | has a | Owner only | [1.4.3 EXAMPLE 4](#143-example-3) | +| A business partner having assigned a legal entity, a site and its main address[^5], which is also the legal address. | Legal and Site Main Address[^5] | has a | has a | has a | Owner only | [1.4.4 EXAMPLE 4](#144-example-4) | +| A business partner having assigned a legal entity, a site and one of its addresses, which is neither the legal address nor the main address[^5] of that site. | Additional Address | has a | has a | has a | Owner only | [1.4.5 EXAMPLE 5](#145-example-5) | + +These are the attributes of the business partner: + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| External ID | The identifier which uniquely identifies (in the internal system landscape of the Sharing Member) the business partner. | String | +| Name Parts | The list of name parts of the business partner to accommodate the different number of name fields in different systems. | List of String | +| Identifiers | The list of identifiers of the business partner. | List of [Business Partner Identifier](#15211-business-partner-identifier) | +| Roles | One or more of the roles, the business partner assumes with respect to the Sharing Member: Supplier, Customer. | List of Enum | +| Is Own Company Data | Indicates whether the Sharing Member claims (in the initial upload) the business partner to belong to the Company Data of the Sharing Member.[^2] | Boolean | +| Created At | The date and time when the business partner data record has been created. | Date / Time | +| Updated At | The date and time when the business partner data record has been last updated. | Date / Time | +| Legal Entity | The legal entity, on which the business partner provides a view. | [Legal Entity Representation](#15212-legal-entity-representation) | +| Site | The site, on which the business partner provides a view. | [Site Representation](#15213-site-representation) | +| Address | The address, on which the business partner provides a view. | [Address Representation](#15214-address-representation) | + +##### 1.5.2.1.1 BUSINESS PARTNER IDENTIFIER + +A business partner identifier (uniquely) identifies the business partner, such as the German Handelsregisternummer, a VAT number, etc. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Value | The value of the identifier like “DE123465789” | String | +| Type | The type of the identifier. | [Identifier Type](#1527-identifier-type) | +| Issuing Body | The name of the official register, where the identifier is registered. For example, a Handelsregisternummer in Germany is only valid with its corresponding Registergericht and Registerart. | String | + +##### 1.5.2.1.2 LEGAL ENTITY REPRESENTATION + +A legal entity representation adds context information to the legal entity, on which the business partner provides a view. Additionally, it contains some of the information from the assigned legal entity. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ---------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| Legal Entity BPN | The BPNL of the legal entity, on which the business partner provides a view. | String | +| Legal Name | The name of the legal entity, on which the business partner provides a view, according to official registers. | String | +| Short Name | The abbreviated name of the legal entity, on which the business partner provides a view. | String | +| States | The list of (temporary) states of the legal entity. | List of [Legal Entity State](#152121-legal-entity-state) | +| Legal Form | The legal form of the legal entity, on which the business partner provides a view. | [Legal Form](#1522-legal-form) | + +###### 1.5.2.1.2.1 LEGAL ENTITY STATE + +A legal entity state indicates if the legal entity is active or inactive[^3]. This does not describe the relation between a Catena-X Member and a business partner and whether they have active business, but it describes whether the legal entity is still operating. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ------------------------------------------------ | ----------------------------------------- | +| Valid From | The date and time from which the state is valid. | Date / Time | +| Valid To | The date and time until the state is valid. | Date / Time | +| Type | One of the state types: active, inactive. | Enum | + +##### 1.5.2.1.3 SITE REPRESENTATION + +A legal entity representation adds context information to the site, on which the business partner provides a view. Additionally, it contains some of the information from the assigned site. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Site BPN | The BPNS of the site, on which the business partner provides a view. | String | +| Name | The name of the site, on which the business partner provides a view. This is not according to official registers but according to the name the owner chooses. | String | +| States | The list of the (temporary) states of the site. | List of [Site State](#152131-site-state) | + +###### 1.5.2.1.3.1 SITE STATE + +A site state indicates if the site is active or inactive[^3]. This does not describe the relation between a Catena-X Member and a business partner and whether they have active business, but it describes whether the site is still operating. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ----------------------------------------- | ----------------------------------------- | +| Valid From | The date from which the state is valid. | String | +| Valid To | The date until the state is valid. | String | +| Type | One of the state types: active, inactive. | Enum | + +##### 1.5.2.1.4 ADDRESS REPRESENTATION + +An address representation adds context information to the address, on which the business partner provides a view. Additionally, it contains most of the information from the assigned address. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| Address BPN | The BPNA of the address, on which the business partner provides a view. | String | +| Name | The name of the address, on which the business partner provides a view. This is not according to official registers but according to the name the sharing members agree on, such as the name of a gate or any other additional names that designate the address in common parlance. | String | +| States | The list of (temporary) states of the address. | List of [Address State](#152141-address-state) | +| Type | One of the address types: Legal Address, Site Main Address[^5], Legal and Site Main Address[^5], Additional Address. | Enum | +| Physical Postal Address | The physical postal address of the address, on which the business partner provides a view, such as an office, warehouse, gate, etc. | [Physical Postal Address](#1523-physical-postal-address) | +| Alternative Postal Address | The alternative postal address of the address, on which the business partner provides a view, for example if the goods are to be picked up somewhere else. | [Alternative Postal Address](#1524-alternative-postal-address) | + +###### 1.5.2.1.4.1 ADDRESS STATE + +An address state indicates if the address is active or inactive[^3]. This does not describe the relation between a Catena-X Member and a business partner and whether they have active business, but it describes whether the business partner is still operating at that address. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ----------------------------------------- | ----------------------------------------- | +| Valid From | The date from which the state is valid. | String | +| Valid To | The date until the state is valid. | String | +| Type | One of the state types: active, inactive. | Enum | + +#### 1.5.2.2 LEGAL FORM + +A legal form is a mandatory corporate legal framework by which companies can conduct business, charitable or other permissible activities. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Technical Key | The technical identifier of the legal form according to [ISO 20275](https://en.wikipedia.org/wiki/ISO_20275). | String | +| Name | The name of legal form according to [ISO 20275](https://en.wikipedia.org/wiki/ISO_20275). | String | +| Abbreviation | The abbreviated name of the legal form according to [ISO 20275](https://en.wikipedia.org/wiki/ISO_20275), such as AG for German Aktiengesellschaft. | String | + +#### 1.5.2.3 PHYSICAL POSTAL ADDRESS + +A physical postal address describes the physical location of an office, warehouse, gate, etc. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| Geographic Coordinates | The exact location of the physical postal address in latitude, longitude, and altitude. | [Geographic Coordinate](#1526-geographic-coordinates) | +| Country | The two-letter country code of the physical postal address according to [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1). | String | +| Administrative Area Level 1 | The administrative area of the physical postal address, such as a region within a country. | [Administrative Area (Level 1)](#1525-administrative-area-level-1) | +| Administrative Area Level 2 | The name of the locally regulated secondary country subdivision of the physical postal address, such as county within a country. | String | +| Administrative Area Level 3 | The name of the locally regulated tertiary country subdivision of the physical address, such as townships within a country. | String | +| Postal Code | The alphanumeric identifier (sometimes including spaces or punctuation) of the physical [postal address](https://en.wikipedia.org/wiki/Address_(geography)) for the purpose of sorting [mail](https://en.wikipedia.org/wiki/Mail), synonyms: postcode, post code, PIN or ZIP code. | String | +| City | The name of the city of the physical postal address, synonyms: town, village, municipality. | String | +| District | The name of the district of the physical postal address which divides the city in several smaller areas. | String | +| Street | The street of the physical postal address, synonyms: road, avenue, lane, boulevard, highway | [Street](#15231-street) | +| Company Postal Code | The company postal code of the physical postal address, which is sometimes required for large companies. | String | +| Industrial Zone | The industrial zone of the physical postal address, designating an area for industrial development, synonym: industrial area. | String | +| Building | The alphanumeric identifier of the building addressed by the physical postal address. | String | +| Floor | The number of a floor in the building addressed by the physical postal address, synonym: level. | String | +| Door | The number of a door in the building on the respective floor addressed by the physical postal address, synonyms: room, suite. | String | + +##### 1.5.2.3.1 STREET + +A street is a public road in a city, town, or village, typically with houses and buildings on one or both sides, synonyms: road, avenue, lane, boulevard, highway. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | +| Name Prefix | The street related information, which is usually printed before the official street name on an address label. | String | +| Additional Name Prefix | The additional street related information, which is usually printed before the official street name on an address label. | String | +| Name | The name of the street. | String | +| Name Suffix | The street related information, which is usually printed after the official street name on an address label. | String | +| Additional Name Suffix | The additional street related information, which is usually printed after the official street name on an address label. | String | +| House Number | The alphanumeric identifier representing the exact location of a building within the street. | String | +| House Number Supplement | The alphanumeric identifier representing the exact location of a business partner in a building. Note this information might be further detailed out semantically in the building, floor, and door attributes. However, this attribute is the only relevant for addressing the business partner. | String | +| Milestone | The alphanumeric identifier representing the exact location of an addressed object within a street without house numbers, such as within long roads. | String | +| Direction | The cardinal direction describing where the exit to the location of the addressed object on large highways / motorways is located, such as Highway 101 South. | String | + +#### 1.5.2.4 ALTERNATIVE POSTAL ADDRESS + +An alternative postal address describes an alternative way of delivery for example if the goods are to be picked up somewhere else. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | +| Geographic Coordinates | The exact location of the alternative postal address in latitude, longitude, and altitude. | [Geographic Coordinate](#1526-geographic-coordinates) | +| Country | The two-letter country code of the postal address according to [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1). | String | +| Administrative Area Level 1 | The administrative area of the alternative postal address, such as a region within a country. | [Administrative Area (Level 1)](#1525-administrative-area-level-1) | +| Postal Code | The alphanumeric identifier (sometimes including spaces or punctuation) of the physical [postal address](https://en.wikipedia.org/wiki/Address_(geography)) for the purpose of sorting [mail](https://en.wikipedia.org/wiki/Mail), synonyms: postcode, post code, PIN or ZIP code. | String | +| City | The name of the city of the physical postal address, synonyms: town, village, municipality. | String | +| City | The name of the city of the alternative postal address, synonyms: town, village, municipality. | String | +| Delivery Service Type | One of the alternative postal address types: P.O. box, private bag, boite postale. | Enum | +| Delivery Service Qualifier | The qualifier uniquely identifying the delivery service endpoint of the alternative postal address in conjunction with the delivery service number. In some countries for example, entering a P.O. box number, postal code and city is not sufficient to uniquely identify a P.O. box, because the same P.O. box number is assigned multiple times in some cities. | String | +| Delivery Service Number | The number indicating the delivery service endpoint of the alternative postal address to which the delivery is to be delivered, such as a P.O. box number or a private bag number. | String | + +#### 1.5.2.5 ADMINISTRATIVE AREA (Level 1) + +An administrative area (level 1) is the country subdivision according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), such as regions within a country. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Name | The name of the country subdivision according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). | String | +| Code | The six-character alphanumeric code according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), consisting of the two-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code and a three-character alphanumeric code for the subdivision in that country, separated by a hyphen. | String | + +#### 1.5.2.6 GEOGRAPHIC COORDINATES + +Geographic coordinates describe an exact location in latitude, longitude, and altitude, according to [ISO 6709](https://en.wikipedia.org/wiki/ISO_6709) with [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84) as the currently only supported coordinate reference system. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Longitude | The geographic coordinate of a place indicating the distance to the west or east of the line passing through Greenwich, in decimal degrees ([DD](https://en.wikipedia.org/wiki/Decimal_degrees)). | Float | +| Latitude | The geographic coordinate of a place indicating its distance to the north or south of the equator, in decimal degrees ([DD](https://en.wikipedia.org/wiki/Decimal_degrees)). | Float | +| Altitude | The geographic coordinate of a place indicating its height above mean sea level, in meters. | Float | + +#### 1.5.2.7 IDENTIFIER TYPE + +![Identifier Type](./assets/IdentifierType.png) + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| --------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Technical Key | The technical identifier of the identifier type. | String | +| Name | The name of the identifier type. | String | +| Business Partner Type | One of the types of business partners for which the identifier is valid: legal entity, address | Enum | + +#### 1.5.2.8 SHARING STATE ENTRY + +![Sharing State Entry](./assets/SharingStateEntry.png) + +A sharing state entry shows the progress in the sharing process and is updated each time the progress for a business partner changes. The business partner is identified by the external ID. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | +| External ID | The external ID of the business partner for which the sharing state entry was created. | String | +| Sharing State Type | One of the sharing state types of the current sharing state: pending, success, error. | Enum | +| Sharing Error Code | One of the sharing error codes in case the current sharing state type is “error”: sharing process error, sharing timeout, BPN not in pool. | Enum | +| Sharing Process Started At | The date and time when the processing of the business partner data record started. | Date / Time | + +#### 1.5.2.9 CHANGELOG ENTRY + +![Changelog Entry](./assets/ChangelogEntry.png) + +An entry of the changelog, which is created each time a business partner is modified and contains data about the change. The actual new state of the business partner is not included. + +| **Attribute** | **Description** | **(Data) Type / Code List / Enumeration** | +| -------------- | ---------------------------------------------------------------------------------- | ----------------------------------------- | +| External ID | The external ID of the business partner for which the changelog entry was created. | String | +| Changelog Type | One of the actions for which the changelog entry was created: create, update. | Enum | +| Timestamp | The date and time when the changelog entry was created. | Date / Time | + +## 2 BUSINESS PARTNER GATE API \[NORMATIVE\] + +The Business Partner Gate API allows to upload and download business partner data records to improve their quality and enrich them with additional information. The Gate API **MUST** be implemented based on the [OpenAPI 3.0.1 specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md). + +### 2.1 PRECONDITIONS AND DEPENDENCIES + +To run the API the following **SHOULD** be set up: https://github.com/eclipse-tractusx/bpdm/blob/release/6.0.x/README.md + +### 2.2 API SPECIFICATION + +#### 2.2.1 API ENDPOINT & RESOURCES + +The Gate API **MUST** be implemented as defined in the following OpenAPI document: https://raw.githubusercontent.com/eclipse-tractusx/bpdm/release/6.0.x/docs/api/gate.json + +The resources **MUST** use the well-known HTTP request methods for CRU(D) operations: + +- POST method **MUST** be used for create requests +- PUT[^4] method **MUST** be used for update requests +- GET method **MUST** be used for read requests + +The POST method MAY also be used for read requests, if input is not given by parameters but rather by an HTTP body to bypass maximum URL length. The PUT method MAY also be used for upsert requests (create or update) if this is required. A state (active / inactive) at each entity **MUST** be used for a soft delete, so that the DELETE method SHALL NOT be used. Other HTTP request methods SHALL NOT be used, including PATCH. + +To facilitate the compliance assessment, this chapter additionally lists and describes the API resources of the Gate API per API controller. + +The following API controllers of the OpenAPI document **MUST** be implemented: + +- Business Partner controller +- Sharing state controller +- Changelog controller + +Uploading and downloading data to/from the Gate API **MUST** follow a staging concept with two stages, so that consumers of the Gate API can compare what they have uploaded (input stage) against what has been corrected and/or enriched by BPDM (output stage). The following controllers **MUST** distinguish between an input and an output stage: + +- Business Partner controller +- Changelog controller + +Note that all resources of the OpenAPI document described in the following are MANDATORY. Conversely, all resources not described in the following are **OPTIONAL**. + +#### 2.2.1.1 BUSINESS PARTNER CONTROLLER + +The business partner controller **MUST** allow to create, update, or read business partners in the input and read from the output stage. It **MUST** have the following resources: + +| **Business Partner Controller Resources** | **Description** | +| ----------------------------------------- | ----------------------------------------------------------------------------------- | +| PUT/input/business-partners | Creates business partners or updates existing business partners in the input stage. | +| POST/input/business-partners/search | Returns business partners by an array of external IDs from the input stage. | +| POST/output/business-partners/search | Returns business partners by an array of external IDs from the output stage. | + +#### 2.2.1.2 SHARING STATE CONTROLLER + +The sharing state controller **MUST** allow to read sharing state entries of business partners. A sharing state of type "Success" **SHOULD** include the assigned BPNL, BPNS and BPNA. The sharing state controller **MUST** have the following resources: + +| **Sharing State Controller Resources** | **Description** | +| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| GET/sharing-state | Returns sharing states of business partners, optionally filtered by an array of external IDs. | + +#### 2.2.1.3 CHANGELOG CONTROLLER + +The changelog controller **MUST** allow to read business partner change log entries. It **MUST** have the following resources: + +| **Changelog Controller Resources** | **Description** | +| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| POST/input/business-partners/changelog/search | Returns change log entries as of a specified timestamp from the input stage, optionally filtered by an array of external IDs. | +| POST/output/business-partners/changelog/search | Returns change log entries as of a specified timestamp from the output stage, optionally filtered by an array of external IDs. | + +### 2.2.2 AVAILABLE DATA TYPES + +The API **MUST** use JSON as the payload format transported via HTTP. Other formats can be added. These are then, however, **OPTIONAL**. + +### 2.2.3 DATA ASSET STRUCTURE + +The following data assets **MUST** be registered at the Core Service Provider so that the Sharing Member can negotiate an API usage contract with the Core Service Provider and access its dedicated BPDM Gate (hosted by the Core Service Provider) through these data assets[^6]: + +| **Type** | **Subject** | **Version** | **Description** | +| -------- | ------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| BPDMGate | FullAccessGateInputForSharingMember | 6.0 | Grants the Sharing Member full access to the input persistence. This can be used to read business partner data in the input persistence, and create / update business partner data in the input persistence from data sources of the Sharing Member. To that end, it also grants read access to the input changelog entries. | +| BPDMGate | ReadAccessGateInputForSharingMember | 6.0 | Grants the Sharing Member read access to the input persistence. This can be used explicitly for value-added services to read business partner data from the input persistence. To that end, it also grants read access to the input changelog entries. | +| BPDMGate | ReadAccessGateOutputForSharingMember | 6.0 | Grants the Sharing Member read access to the output persistence. This can be used to read business partner data from the output persistence so that the data sources of the Sharing Member can be updated. Furthermore, it can be used to update data sources in value-added services. To that end, it also grants read access to the output changelog and sharing state entries. | + +Example data asset ([*dct:type*](https://purl.org/dc/terms/type) for asset type, [*dct:subject*](https://purl.org/dc/terms/subject) for asset subject, [*dct:description*](https://purl.org/dc/terms/description) for asset description and *cx-common:version* for asset version from the table above): + +```json +{ + "@context": { + "dct": "https://purl.org/dc/terms/", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "cx-common": "https://w3id.org/catenax/ontology/common#", + }, + "@type": "Asset", + "@id": "a8f15946-2347-47a8-a67f-846e7303fd94", + "properties": { + "dct:type": { + "@id": "cx-taxo:BPDMGate" + }, + "dct:subject": { + "@id": "cx-taxo:FullAccessGateInputForSharingMember" + }, + "dct:description": "Grants the Sharing Member full access to the input persistence. This can be used to read business partner data in the input persistence, and create / update business partner data in the input persistence from data sources of the Sharing Member. To that end, it also grants read access to the input changelog entries.", + "cx-common:version": "6.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "https:///companies//api/v6/", + "oauth2:tokenUrl": "https:///auth/realms//protocol/openid-connect/token", + "oauth2:clientId": "", + "oauth2:clientSecretKey": "", + "proxyMethod": true, + "proxyPath": true, + "proxyQueryParams": true, + "proxyBody": true + } +} +``` + +The OAuth2 client permissions **MUST** be configured to solely allow access to the API resources defined in the corresponding asset, checking HTTP method (read vs. full access), path (e.g. for input / output / sharing state), query parameters and body of the HTTP request sent to the data plane public API which acts as a proxy for the BPDM Gate API[^7]. + +### 2.2.4 ERROR HANDLING + +The following http response codes **MUST** be defined for all resources: + +- 200 - OK +- 400 - Bad Request +- 401 - Unauthorized +- 403 - Forbidden +- 404 - Not Found +- 500 - Internal Server Error + +HTTP Status Code Registry **MUST** be adhered to in the implementation for the decision on when to use which error code: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml + +### 2.2.5 ADDITIONAL REQUIREMENTS + +#### 2.2.5.1 CONVENTIONS FOR USE CASE POLICY IN CONTEXT OF DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +#### 2.2.5.2 ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number. + +- Membership +- BPNL + +#### 2.2.5.3 ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +## 3 REFERENCES + +## 3.1 NORMATIVE REFERENCES + +- [Gate API specification 6.0.x](https://raw.githubusercontent.com/eclipse-tractusx/bpdm/release/6.0.x/docs/api/gate.json) +- [ISO 20275](https://en.wikipedia.org/wiki/ISO_20275) +- [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) + - [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) + - [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) + +- [ISO 6709](https://en.wikipedia.org/wiki/ISO_6709) +- [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84) + +## 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- [BPDM Catena-X Website](https://catena-x.net/en/offers-standards/bpdm) + +## REFERENCE IMPLEMENTATION + +> *This section is non-normative* + +- [Business Partner Gate API 6.0.x](https://github.com/eclipse-tractusx/bpdm/tree/release/6.0.x/bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api) + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +The following picture shows the business partner with the business partner relationship as an outlook for one of the next versions of this standard: + +![Business Partner with Relationship](./assets/BusinessPartnerWithRelationship.png) + +The idea is to use the business partner relationship to upload different kinds of relations between two business partners, such as: + +- a business partner is the legal entity for another business partner +- a business partner is replaced by another business partner + +It is not intended to use the business partner relationship for legal hierarchies (majority shareholding). + +### TABLES + +> *This section is non-normative* + +Intentionally left blank. + +[^1]: Note that PlantUml is used for the conceptual UML diagrams in this document (A = abstract class; green E = entity; C = class; red E = enumeration). An abstract class has no actual representation in the OpenAPI implementation. An entity is usually implemented by an own OpenAPI controller with resources and usually is the root in a payload, while a class is a sub node in the payload. An enumeration is a set of predefined values. + +[^2]: Note that each data record in the MDM business partner data of the Sharing Member does not explicitly have to be flagged as "is own company data". However, it is important that the Sharing Member flags business partners as "is own company data" in the initial upload of own Company Data, such as by introducing a constant in the used middleware. + +[^3]: Note that this a currently a soft-delete approach and not a business state. However, this can be adapted in the next version of this standard. + +[^4]: Note that in case of a PUT the corresponding resources expect to receive the full updated record, including values that did not change. + +[^5]: Note that there is currently a debate as to whether a site is only a consolidation of addresses (BPNA), with all addresses being equally ranked, since a "main" address can't always be defined at this point in time. This may lead to changes in the next update of this standard. + +[^6]: Note that the Sharing Member assumes the roles Data Provider on upload and Data Consumer on download of business partner data, while the Core Service Provider assumes the roles Data Consumer on upload and Data Provider on download of business partner data. + +[^7]: Note that the definition of the data assets depends on the current implementation state of the reference implementation (Tractus-X Eclipse Dataspace Connector). Therefore the data assets represent permissions on APIs, whereas they should actually only represent APIs. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/AdditionalAddressWithSite.png b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/AdditionalAddressWithSite.png new file mode 100644 index 000000000..a44c42f0f Binary files /dev/null and b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/AdditionalAddressWithSite.png differ diff --git a/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/AdditionalAddressWithoutSite.png b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/AdditionalAddressWithoutSite.png new file mode 100644 index 000000000..62c650fe3 Binary files /dev/null and b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/AdditionalAddressWithoutSite.png differ diff --git a/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/BusinessPartner.png b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/BusinessPartner.png new file mode 100644 index 000000000..bded65c31 Binary files /dev/null and b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/BusinessPartner.png differ diff --git a/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/BusinessPartnerWithRelationship.png b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/BusinessPartnerWithRelationship.png new file mode 100644 index 000000000..4197b1480 Binary files /dev/null and b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/BusinessPartnerWithRelationship.png differ diff --git a/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/ChangelogEntry.png b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/ChangelogEntry.png new file mode 100644 index 000000000..d70ffc572 Binary files /dev/null and b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/ChangelogEntry.png differ diff --git a/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/IdentifierType.png b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/IdentifierType.png new file mode 100644 index 000000000..2a77ab21e Binary files /dev/null and b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/IdentifierType.png differ diff --git a/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/LegalAddress.png b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/LegalAddress.png new file mode 100644 index 000000000..64ac2bf54 Binary files /dev/null and b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/LegalAddress.png differ diff --git a/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/LegalAndSiteMainAddress.png b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/LegalAndSiteMainAddress.png new file mode 100644 index 000000000..5d35141a1 Binary files /dev/null and b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/LegalAndSiteMainAddress.png differ diff --git a/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/SharingStateEntry.png b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/SharingStateEntry.png new file mode 100644 index 000000000..ff6992dd0 Binary files /dev/null and b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/SharingStateEntry.png differ diff --git a/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/SiteMainAddress.png b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/SiteMainAddress.png new file mode 100644 index 000000000..b3058eb4c Binary files /dev/null and b/docs/standards/CX-0074-BusinessPartnerGateAPI/assets/SiteMainAddress.png differ diff --git a/docs/standards/CX-0076-GoldenRecordEndtoEndRequirementsStandard/CX-0076-GoldenRecordEndtoEndRequirementsStandard.md b/docs/standards/CX-0076-GoldenRecordEndtoEndRequirementsStandard/CX-0076-GoldenRecordEndtoEndRequirementsStandard.md new file mode 100644 index 000000000..16c5c76cb --- /dev/null +++ b/docs/standards/CX-0076-GoldenRecordEndtoEndRequirementsStandard/CX-0076-GoldenRecordEndtoEndRequirementsStandard.md @@ -0,0 +1,446 @@ +# CX-0076 - Golden Record End-to-End Requirements Standard v1.1.0 + +## ABSTRACT + +*This section is non-normative.* + +When building business data management from disparate data sources, there are often issues with duplicate records, incomplete values within a record, and records with poor data quality. The Golden Record process solves these issues by e.g., data enrichment, typification and improving data quality within a record. The Golden Record is a concept within Master Data Management (MDM) that identifies and defines the single version of truth of business partner data, where truth is understood to be data that is trusted to be accurate, complete, correct and up to date. Thus, the Golden Record represents this trusted and best possible result of a specific business partner data set and ends up with an assigned unique identifier, represented as a Business Partner Number (BPN). + +Updating and maintaining business partner data can be a lengthy, costly, and time-consuming activity that currently has to be undertaken by each company individually. + +The purpose of this standard is to describe guidelines and requirements specific for the challenges of business data maintenance and defines the required quality criteria for Golden Records. These quality criteria not only serve the users of the Golden Record, but also form the basis for all Catena-X use cases. + +## FOR WHOM IS THE STANDARD DESIGNED + +See chapter 1.1 Audience & Scope + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +| Version | Description | Date | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | +| V1.0.0 | Initial release| 22.03.2024 | +| V1.1.0 |
  • Adjustment of Table 2 in chapter [2.1.9](#219-golden-record-output-requirements). Data field references deleted.
  • Street is now neither mandatory nor optional for Japan as listed in Table 2
  • New paragraph added at the end of chapter [2.1.2](#212-upload-criteria-and-mandatory-fields) providing more details on "own data"
  • Chapter [2.1.6](#216-quality-checks-for-legal-entity-including-legal-form) has been expanded specifying expected relations and quality checks in more detail.
  • Chapter [2.1.10 NOTIFICATIONS](#2110-notifications) added.
  • Chapter [2.1.11 CONFIDENCE LEVEL](#2111-confidence-level) added
  • Footnote for tax jurisdiction added in chapter [2.1.8](#218-quality-checks-for-tax-number-and-other-identifier)
    • | 22.06.2024 | | + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +*This section is non-normative.* + +This standard is relevant for the following audience: + +- Core Service Provider +- Business Application Provider +- Data Provider and Consumer + +This document focuses on the outcome of the Golden Record Process. It is relevant for core service providers who want to provide services for retrieving a cleansed, high-quality business partner data record (Golden Record). It is also relevant for business application providers as well as data providers and consumers who want to use such services, and, finally, to assign Business Partner Numbers to respective Golden Records. + +In scope are the requirements of cleansing and enriching the business partner data records with the aim to create a Golden Record proposal. + +Not in scope is the way of how business partner data can be shared to create a Golden Record. Please refer to the Catena-X standard CX-0074 Business Partner Gate API v3.0.0 for more details. + +Not in scope is the overall Business Partner Pool with all Golden Records within Catena-X and the way of how the Golden Records can be retrieved. Please refer to the Catena-X CX-0012 Business Partner Pool API v4.0.0 standard for more details. + +Not in scope is the general definition of the Business Partner L/S/A-logic. Please refer to the Catena-X standard CX-0010 Business Partner Number v2.0.0 standard for more details. + +You can find the other standards in the standard library of Catena-X: https://catena-x.net/de/standard-library. + +### 1.2 CONTEXT + +*This section is non-normative.* + +The establishment of various industry networks (such as Catena-X) has increased the need to establish data standards across the entire automotive value chain and to promote industry-wide, international data exchange. For the networking of OEMs, suppliers, customers, and industrial partners, it is essential to define and introduce a cross-industry standard for the identification of business partners and to provide the corresponding data in a certain quality to increase the usefulness and trust in the provided data in the form of Golden Records. + +### 1.3 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD and SHOULD NOT in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) [[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119 "Key words for use in RFCs to Indicate Requirement Levels")] [[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174 "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words")] when, and only when, they appear in all capitals, as shown here. + +*This section is non-normative.* + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +### 1.4 EXAMPLES + +Not applicable. + +### 1.5 TERMINOLOGY + +*This section is non-normative.* + +#### 1.5.1 GOLDEN RECORD + +Golden Record defines a business partner data record which successfully passed a set of predefined quality rules. These rules qualified the data record into a harmonized, standardized, and semantically unified data structure which is defined by Catena-X. The Golden Record status is a prerequisite for each Business Partner data record to receive a valid Business Partner Number. + +#### 1.5.2 LEGAL ENTITY + +In general, a Legal Entity is a juridical person that has legal rights and duties related to contracts, agreements, and obligations. The term especially applies to any kind of organization (such as an enterprise or company, university, association, etc.) established under the law applicable to a country. + +In Catena-X, a Legal Entity is a type of business partner representing a legally registered organization with its official registration information, such as legal name (including Legal Form, if registered), legal Address and Tax Number. + +A Legal Entity has exactly one legal Address[^6], but it is possible to specify additional Addresses that a Legal Entity owns. Thus, at least one Address is assigned to a Legal Entity. A Legal Entity can own Sites. Thus, many or no Sites are assigned to a Legal Entity.  A Legal Entity is uniquely identified by the BPNL. + +#### 1.5.3 LEGAL FORM + +Legal Form identifies the legal status of a legal person. The classification of Legal Forms is based on the company forms of the Trade Register and on the requirements of taxation legislation. The Legal Forms of enterprises and corporations are recorded in the Business Information System. + +#### 1.5.4 ADDRESS + +In general, an Address is a collection of information to describe a physical location, using, for example, a street name with a house number and/or a post office box as reference. In addition, an Address consists of several postal attributes, such as country, region (state), county, township, city, district, or postal code, which help deliver mail. + +In Catena-X, an Address is a type of business partner representing the legal Address of a Legal Entity, and/or the main Address[^7] of a Site, or any additional Address of a Legal Entity or Site (such as different gates). + +An Address is owned by a Legal Entity. Thus, exactly one Legal Entity is assigned to an Address. An Address can belong to a Site. Thus, one or no Site is assigned to an Address. An Address is uniquely identified by the Business Partner Number Address. + +#### 1.5.5 BPNL BUSINESS PARTNER NUMBER LEGAL ENTITY + +A BPNL represents and uniquely identifies a Legal Entity, which is defined by its legal name (including Legal Form, if registered), legal Address and Tax Number. + +For further details on BPNLs please see standard CX-0010 Business Partner Number v2.0.0. + +#### 1.5.6 BPNS BUSINESS PARTNER NUMBER SITE + +A BPNS represents and uniquely identifies a Site, for example where a production plant, warehouse or office building is located. + +For further details on BPNSs please see standard CX-0010 Business Partner Number v2.0.0. + +#### 1.5.7 BUSINESS PARTNER NUMBER ADDRESS + +A BPNA represents and uniquely identifies an (geographical) Address, which can be the legal Address of a Legal Entity, and/or the main Address of a Site, or any additional Address of a Legal Entity or Site (such as different gates) based on e.g., country, street and city. + +It is important to note that only the BPNL must be used to uniquely identify a Legal Entity. Even in the case that the BPNA represents the legal Address of the Legal Entity, it shall not be used to uniquely identify the Legal Entity. + +For further details on BPNAs please see standard CX-0010 Business Partner Number v2.0.0. + +#### 1.5.8 RELATIONS + +There are relations between a Legal Entity (BPNL), its Sites (BPNS), and its Addresses (BPNA). + +For more information, please refer to the standard standard CX-0010 Business Partner Number v2.0.0. + +#### 1.5.9 TAX NUMBER AND OTHER IDENTIFIER + +The data quality rules are leveraging a variety of identifiers to cross check the correctness of Business Partner data record attributes. This includes Tax identifier issued by a legal authority like for example but not limited to EU VAT ID as well as other commercial Business Partner identification numbers such as for example Dun&Bradstreet-Number (DUNS®), Bureau van Dijk ID (BvD), Global Location Number (GLN) and others. + +## 2 MAIN CONTENT + +The following rules are minimum requirements and may be supplemented. In particular, the reference to ISO standards should be understood as a minimum requirement and may be supplemented by other standards to improve the quality of the datasets. This also applies to the listed countries as described in chapter 2.1.9 Golden Record Output. However, further rules which might be applied by a service provider MUST not conflict with the rules described in this standard. + +To provide a certain level of quality and trustfulness, a series of quality checks MUST be performed. + +### 2.1.1 GENERAL GOLDEN RECORD OUTPUT REQUIREMENTS + +In addition to the specific checks described in the following chapters, some general checks MUST be carried out: + +Generic quality checks: + +- A record MUST be classified as either a Legal Entity (L), Site (S) or Address (A). +- A Site or Site information MUST be defined or marked only by its owner. +- Changes (updates) by a service provider to a record MUST be available in an understandable, comprehensible, and verifiable manner. +- There MAY be at least the original data field input, the change proposal as well as a source where this proposal is coming from to ensure comprehensibility. + +### 2.1.2 UPLOAD CRITERIA AND MANDATORY FIELDS + +Some fields are classified as mandatory from a business perspective and therefore to be uploaded. If one or more of these mandatory fields are missing, a check against official registers or certain validity checks cannot be guaranteed to be successful. To maintain good data quality, the following fields MUST be included in each record for further processing. Therefore, the following rules MUST be carried out: + +Mandatory fields quality checks: + +- Legal name of the company (including the Legal Form, if registered) MUST NOT be empty. +- Country MUST NOT be empty. +- City MUST NOT be empty. +- The External identifier, meaning the unique identifier from the uploading party, MUST NOT be empty. + +Please refer to the CX-0074 Business Partner Gate API v3.0.0 standard for the respective data fields. + +For uploading data, a mechanism MUST be provided to flag uploaded data as "own data", representing that this data belongs to my company. + +There are certain information which can only be provided by the data owner. This applies to: + +Site name +Short name (of the company; e.g. BMW AG instead of the registered legal name Bayerische Motorenwerke Aktiengesellschaft) +Furthermore, the following information are seen as beneficial if the data owner could provide them with the upload: + +- full postal address +- VAT & tax number +- HRB number or respective country specific commercial register + +Service provider must be able to consolidate the site information which is provided by the "site name" information by the sharing member in one or several uploaded data (business partner) records. + +Result of this consolidation MUST be the creation or update of respective BPNS based on the provided information. + +E.g. the field "name 3" of the upload data record contains "Plant/Werk Feuerbach" (identifier/name for the site) and thus refers to this specific site. + +### 2.1.3 FEEDBACK BASED ON DATA INPUT + +Feedback on data upload MUST be provided indicating if an upload was successful or unsuccessful. It MUST be made clear which record was uploaded successfully or not. These checks are to be considered as a minimum and may be substituted by further responses. The following rules MUST be carried out: + +Golden Record response quality checks: + +- The reasons why an upload was not successful MUST be reported. +- It MUST be made transparent if one or more of the mandatory fields are missing. +- If mandatory fields are missing, a self-explanatory error MUST be returned. +- If optional fields are missing, an information MUST be returned. + +### 2.1.4 DUPLICATES CHECK + +By uploading data via the BPDM Gate-API, duplicates may be shared and existent in the Gate persistence of the respective sharing member. There MUST not be any duplicates of the same BPN-type in the BPDM Pool, as this check and the subsequent linkage (See chapter 2.1.5 [Linkage](#215-linkage) for details) MUST be carried out by the service provider. + +Therefore, the following rules MUST be carried out: + +**Duplicates quality checks:** + +- Duplicates MUST be recognized in the process, based on e.g., but not limited to, company name incl. Legal Form, Tax or Other Identifier, and identical Addresses. + +- A de-duplication MUST be performed as part of the Golden Record process. +- As a result of the duplicate check, there MUST be no more duplicates in the CX pool[^1] per BPN-type. This applies for all different types of Business Partner Numbers (BPN)[^2]: Legal Entities (L), Sites (S) and Addresses (A). + +### 2.1.5 LINKAGE + +The linkage answers the following question: Does the current dataset (incoming from a sharing member) already exist in the Catena-X data pool? + +If an uploaded record does not exist in the CX pool with an available BPN, a new BPN MUST be created and linked to the uploaded data record. Otherwise, the existing BPN MUST be used and linked to the uploaded data record. + +The creation of the BPN MUST be performed according to Catena-X standard CX-0010 Business Partner Number v2.0.0. + +### 2.1.6 QUALITY CHECKS FOR LEGAL ENTITY, INCLUDING LEGAL FORM + +The following quality checks are designed to verify that the shared Legal Entity, including the Legal Form, if registered, is correct. + +The following rules MUST be carried out. + +**Quality checks:** Correctness of Legal Entity + +- It MUST be checked, if the Legal Entity incl. Legal Form, based on ISO 20275, is correct. + +It MUST be checked if the Legal Form is valid for this country and formally correct written. + +- Short and/or long form of the Legal Form MUST be identified and extracted. + +- If the combination of a provided identifier, legal name and Address is found in the commercial register or equivalent official register, the type of this record MUST be set to BPNL. + +- In addition, a BPNA MUST be created which receives the *IsLegalAddress* flag, if the duplicate check or linkage does not return a result. + +- When a BPNA is uploaded, a relation to a L MUST be set. + +- When a BPNS is uploaded, a relation to a L MUST be set. + +- The field LegalEntity.LegalForm[^3] MUST be extracted from LegalNameParts according to ISO20275 and written into the LegalForm field. + +- LegalEntity.LegalForm.technicalKey MUST correspond to ISO20275 ELF code. + +- When an additional Business Partner address data set is uploaded which is not a legal entity, and thus a BPNA has to be created yet, a relation to a BPNL MUST be established. + +- If no existing BPNL from the Pool could be identified and assigned, a new corresponding BPNL MUST be created by the service provider including the required data fields. The respective BPNA and the new BPNL must then be linked to each other accordingly. + +- This applies only, if the exact legal entity can be clearly identified based on the given information by the provided input. + +- If this is not unambiguously possible (in cases that no or several possible legal entities were identified), it is recommended, that the party who uploaded the BP-Data and/or the respective data owner MUST be contacted to ensure data accuracy. + +If additional addresses are recognized in the commercial register (or a similar trustworthy source), these MUST be created as AdditionalAddresses (BPNAs). Respective additions to the legal name MUST be included in the AddressName field of the BPNA. + +Example: +Bayerische Motoren Werke Aktiengesellschaft lists several additional addresses. + +For each of this addresses, a BPNA with the AddressName e.g. Bayerische Motoren Werke Aktiengesellschaft Niederlassung Bonn needs to be created. + +### 2.1.7 QUALITY CHECKS FOR ADDRESSES + +The following quality checks are designed to verify that the shared Addresses are correct. The following checks MUST therefore be carried out: + +**Address validation quality checks:** + +- The country code MUST be checked based on ISO 3166-1. For details please see Table 2 in chapter [2.1.9](#219-golden-record-output-requirements) +- The region code MUST be checked based on ISO 3166-2. For details please see Table 2 in chapter [2.1.9](#219-golden-record-output-requirements) +- It MUST be checked that the postal code is valid for the country and fits to the city +- It MUST be checked that the city exists in this country and that it fits to postal code + +### 2.1.8 QUALITY CHECKS FOR TAX NUMBER AND OTHER IDENTIFIER + +The following quality checks are designed to verify that the shared Tax Number or Other Identifier are correct. The following checks MUST be carried out: + +**Tax Number and Other Identifier quality checks:** + +- It MUST be checked that the Tax Number is correct according to national registers and their syntax. +- It MUST be checked that the format of the tax jurisdiction[^10] code is correct. +- It MUST be checked that the format of Other Identifier (such as, but not limited to DUNS, LEI, EIN, UBI, GLN) is valid. +- The consistency between Canadian Business Number and GST MUST be checked (Good and Service Tax Number) +- The issuing body MUST be filled in, to be able to correctly assign the responsible commercial register when data records are uploaded for a Legal Entity including the corresponding commercial register number. + This quality check applies to Tax Numbers assigned to a specific commercial register or similar, such as, but not limited to, the German Handelsregisternummer. + +### 2.1.9 GOLDEN RECORD OUTPUT REQUIREMENTS + +The requirements described below relate to the expected outcome after the Golden Record process has been carried out. There are country specific rules and (mandatory/optional) attributes. Depending on the country the e.g., type of identifier and/or the format, can be different. + +Below is a list of countries for which a rule has been defined. If a rule says, "Applies to all countries", the full list in Table 1 MUST be applied. Exceptions will be specified. + +There is also a rule-specific list of data fields in which the result MUST be written. This will be stated in column Attribute (Date Model). For details on the data model, please see CX 0012 Business Partner Pool API and CX 0074 Business Partner Gate API v3.0.0. + +***Table 1: Country List based on ISO 3166-1*** + +|Countries||||||| +| - | - | - | - | - | - | - | +|AD|CL|GE|IS|MC|PL|TJ| +|AE|CN|GH|IT|MD|PT|TM| +|AL|CO|GI|JM|ME|PY|TN| +|AM|CR|GP|JP|MK|QA|TR| +|AR|CU|GR|KE|MT|RO|TT| +|AT|CY|GT|KG|MX|RS|TW| +|AU|CZ|HK|-|MY|RU|UA| +|AZ|DE|HN|KR|NA|SA|UK\*| +|BA|DK|HR|KW|NI|SE|US\*\*| +|BE|DZ|HT|KZ|NL|SG|UY| +|BG|EC|HU|LB|NO|SI|UZ| +|BO|EE|ID|LK|NZ|SK|VA| +|BR|EG|IE|LT|PA|SM|VE| +|BY|ES|IL|LU|PE|SN|VN| +|CA|FI|IN|LV|PH|SV|XK| +|CH\*\*\*|FR|IR|MA|PK|TH|ZA| +|||||||ZW| + +\* UK includes North Ireland, GG, JE, \*\* US includes PR, \*\*\* CH includes LI + +The following information rules MUST apply: + +- For countries listed below as mandatory, an error message MUST be given if the rule could not be applied. +- For countries listed below as optional, an info message MUST be given if the rule could not be applied. +- A rule is not relevant for a country if it’s not listed as mandatory or optional. No specific response is expected in this case. + +***Table 2: Country specific business rules*** +|**Business Rule**|**Affected Country**| +| - | - | +|Registered name (Legal Entity incl. Legal Form, if registered) MUST be set.|**Mandatory for:**
    Applies to all countries as defined in Table 1.| +|Tax Number MUST be set.|**Mandatory for:**
    Applies to all countries as defined in Table 1.
    **Exception,** neither mandatory nor optional for: CR, CU, IR, KW, LB, VA. | +|External identifier – number MUST be set.| **Mandatory for:**
    Applies to all countries as defined in Table 1.| +|External identifier – number|**Optional for:** Applies to all countries as defined in Table 1.| +|External identifier - type |**Optional for:**
    Applies to all countries as defined in Table 1.| +|Country MUST be set|**Mandatory for:**
    Applies to all countries as defined in Table 1.
    **Exception**, neither mandatory nor optional: CN | +|Region, state MUST be set|**Mandatory for:**
    BR, CA, CZ, IN, MX, RU, US(PR)
    **Optional for:**
    AD, AL, AM, AR, AT, AU, AZ, BA, BE, BG, BO, BY, CH/LI, CL, CO, CR, CU, CY, DE, DK, DZ, EC, EE, ES, FI, FR, GE, GI, GR, GT, HN, HR, HT, HU, IE, IS, IT, JM, JP, KG, KZ, LB, LT, LU, LV, MC, MD, ME, MK, MT, MY, NI, NL, NO, PA, PE, PH, PL, PT, PY, RO, RS, SE, SI, SK, SM, SV, TH, TJ, TM, TR, TT, UA, UK/JE/GG, UY, UZ, VA, VE,

    **Neither mandatory nor optional:**
    AE, CN, EG, GH, GP, HK, ID, IR, IL, KE, KR, KW, MA, NA, NZ, PK, QA, SA, SN, SG, ZA, LK, TW, TN, VN, XK, ZA, ZW| +|Secondary region (county) - Sub-province MUST be set|**Optional for**:
    Applies to all countries as defined in Table 1.
    **Exception,** mandatory for: RU
    **Exception**, neither mandatory nor optional for:
    AE, DZ, AU, EG, GH, GP, HK, IN, ID, IR, IL, JP, KE, KR, KW, MY, MA, NA, NZ, PK, PH, QA, SA, SN, SG, ZA, LK, TW, TH, TN, AE, VN, XK, ZW| +|Tertiary region (township) - Sub-province 2 MUST be set|**Optional for**:
    Applies to all countries as defined in Table 1.
    **Exception**, neither mandatory nor optional:
    AE, DZ, AU, EG, GH, GP, HK, ID, IR, IL, JP, KE, KW, MY, MA, NA, NZ, PK, PH, QA, SA, SN, SG, ZA, LK, TW, TH, TN, AE, VN, XK, ZW| +|Sub-province 3 MUST be set|**Optional for**:
    Applies to all countries as defined in Table 1.
    **Exception**, neither mandatory nor optional for:
    AE, DZ, AU, EG, GH, GP, HK, ID, IR, IL, JP, KE, KW, MY, MA, NA, NZ, PK, PH, QA, SA, SN, SG, ZA, LK, TW, TH, TN, AE, VN, XK, ZW| +|District/Sub-locality MUST be set|**Optional for**:
    Applies to all countries as defined in Table 1.
    **Exception**, neither mandatory nor optional for:
    AE, DZ, AU, GH, GP, HK, ID, IR, IL, KE, KR, KW, MY, NA, NZ, PH, QA, SN, SG, ZA, LK, AE, VN, XK, ZW, | +|Sub-locality 2 MUST be set |**Optional for:**
    Applies to all countries as defined in Table 1.
    **Exception,** neither mandatory nor optional for:
    AE, DZ, AU, CN, EG, GH, GP, HK, IR, IL, JP, KE, KR, KW, MY, MA, NA, NZ, PK, PH, QA, SA, SN, SG, ZA, LK, TW, TH, TN, AE, VN, XK. ZW, | +|City MUST be set |**Mandatory for:**
    Applies to all countries as defined in Table 1.| +|Postal code MUST be set|**Mandatory for:**
    Applies to all countries as defined in Table 1.
    **Exception**, neither mandatory nor optional for:
    BO, HK, JM, LB, QA, AE, ZW| +|Street MUST be set|**Mandatory for:**
    Applies to all countries as defined in Table 1.
    **Exception**, neither mandatory nor optional for:
    QA, AE, JP| +|House number MUST be set|**Optional for:**
    Applies to all countries as defined in Table 1.
    **Exception**, neither mandatory nor optional:
    AE, GH, GP, IR, KE, KW, LB, NA, QA, SA, SN, TW, ZW| +|AlternativePostalAddress|**Optional for:**
    Applies to all countries as defined in Table 1.
    **Exception**, neither mandatory nor optional for:
    AE, AU, CN, DZ, EG, GH, GP, HK, ID, IL, IN, IR, JP, KE, KR, KW, LB, LK, MA, MY, NA, NZ, PH, PK, QA, SA, SG, SN, TH, TN, TW, XK, ZA, ZW| +|AlternativePostalAddress|**Optional for:**
    Applies to all countries as defined in Table 1.
    **Exception**, neither mandatory nor optional:
    AE, AU, CN, DZ, EG, GH, GP, HK, ID, IL, IN, IR, JP, KE, KR, KW, LB, LK, MA, MY, NA, NZ, PH, PK, QA, SA, SG, SN, TH, TN, TW, XK, ZA, ZW| +|Business Partner Type (Legal Entity (L), Site (S), (logistical) Address (A))|**Mandatory for:**
    Applies to all countries as defined in Table 1.| +|"BPNA belongs to Legal Entity (BPNL)"|**Mandatory for:**
    Applies to all countries as defined in Table 1.| + +### 2.1.10 NOTIFICATIONS + +A notification[^8] mechanism MUST be established to provide information per data record + +- on the current processing status of a particular record, +- in the event of errors, +- and on any type of content change, e.g. comparison of data before and after golden record process, in relation to that particular record. + +An additional user interface MUST be provided to visualize these notifications as well as the related information. + +In case of shared records by a sharing member, respective notifications MUST be made available, e.g. via a change log. + +A confidence level MUST be calculated and assigned to BPNLs and BPNAs to indicate the data quality. + +### 2.1.11 CONFIDENCE LEVEL + +The confidence level MUST be calculated based on the following quality dimensions in this ranked order from low to high: + +Used by (low, e.g. value 1[^9]) +Checked by and (mid, e.g. value 3) +approved by data owner (high, e.g. value 5) + +**Used by:** + +To be understood as "more as one cx member" is using this Business Partner data record. +Grant e.g. 1 point, if this record is used by one or more members. + +**Checked by:** + +To be understood as "checked and validated by a trustworthy source (e.g. commercial registers). This applies only for BPNL and not for BPNS or BPNA. Used sources MUST be made transparent. Grant e.g. 3 points, if the data record got successfully validated. + +**Approved by data owner:** + +To be understood as data record was provided by data owner. +Grant e.g. 5 points, if the data owner flag is set. + +Regular validations of the used by and checked by checks MUST be ensured once every six months and detected errors must be corrected in a timely manner. + +**Calculation example:** + +The higher the points, the higher the confidence level. + +In case respective address types, representing a BP Legal Entity, BP Site, or BP Address, can be shared by the data owner, a mechanism MUST be provided to also define respective relations between this uploaded data. (E.g. that an BP Address belongs to a specific BP Legal Entity.) + +This could be based, for example, on the external identifier. + +This mechanism MUST be applied to data records of an initial upload where no Business Partner Numbers has been assigned yet. + +After having passed the Golden Record process, relation information MUST be available on the BPN-relations as well as per the mechanism as described above. + +### 2.2 OUT OF SCOPE + +This standardization document does not describe the process and functionality to achieve the required results. Each operational provider is free to define the appropriate execution logic to achieve the result as defined in this standard. + +### 2.3 DATA QUALITY RULE ACCESSIBILITY + +The quality checks as described in this standard are using the input based on the Business Partner Gate API with the respective endpoints. For further details please refer to Catena-X standard CX-0074 Business Partner Gate API v3.0.0. + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +Intentionally left blank. + +### 3.2 NON-NORMATIVE REFERENCES + +*This section is non-normative.* + +- [BPDM Catena-X Website](https://catena-x.net/en/offers/bpdm) +- CX – 0010 Business Partner Number v2.0.0 +- CX – 0012 Business Partner Pool API v4.0.0 +- CX – 0074 Business Partner Gate API v3.0.0 + +### 3.3 REFERENCE IMPLEMENTATIONS + +*This section is non-normative.* + +## ANNEXES + +### FIGURES + +*This section is non-normative.* + +Intentionally left blank. + +### TABLES + +*This section is non-normative.* + +Intentionally left blank. + +[^1]: For details related to the Pool API, please see standard CX-0012 Business Partner Data Pool API v4.0.0. + +[^2]: For details related to the Business Partner number and the different types, please see standard CX-0010 Business Partner Number v2.0.0. + +[^3]: For details on the data model and data fields please refer to the standard CX-0074 Business Partner Gate API standard v3.0.0. + +[^4]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf + +[^5]: https://catena-x.net/de/standardisierung/catena-x-einfuehren-umsetzen/standardisierung/standard-library + +[^6]: Although in some cases there can be more than one legal address assigned to the same legal entityE.g. Siemens in Germany (Berlin & Munich). This might lead to changes to data model definitions including relations in the future. + +[^7]: Note that there is currently a debate that a site is a consolidation of addresses (BPNA), with all addresses being equally ranked, since a "main" address can't always be defined at this point in time. This may lead to changes in the next update of this standard. + +[^8]: Notification is to be understood as an information (info, warning, error) to be provided to the user. It's not to be understood as a short term notification similar to a e.g. 30 second pop up message. + +[^9]: Numbers (values) are to be seen as examples to make the calculation more easy to understand. + +[^10]: This requirement is valid, however, the data model as described in CX-0074 Business Partner Gate API v3.0.0 and CX-0012 Business Partner Pool API v4.0.0 does not provide respective fields yet. This will be probably provided with standard release 24.08. Thus, a certification to this requirement can not happen as of today until the data model got extended accordingly. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0077-DataQualityDashboard/CX-0077-DataQualityDashboard.md b/docs/standards/CX-0077-DataQualityDashboard/CX-0077-DataQualityDashboard.md new file mode 100644 index 000000000..517572bd4 --- /dev/null +++ b/docs/standards/CX-0077-DataQualityDashboard/CX-0077-DataQualityDashboard.md @@ -0,0 +1,414 @@ +# CX-0077 Data Quality Dashboard v1.2.0 + +## ABSTRACT + +The Data Quality Dashboard (DQD) has to rely on a set of clearly defined quality rules +which is the basis of the Golden Record Process and secures the syntactical and logical correctness of mission-critical business partner data attributes. To secure global consistency the DQD rule relies on defined ISO norms as defined in this document- – see Standardization Document CX-0076 Version 1.1.0, Golden Record EndtoEnd Requirements Standard. DQD has to capture at least 112 countries based on ISO 3166-1. DQD has to validate BP data records in the Inbound and Outbound Persistence of the related Catena-X (CX) Member who licensed DQD. Each DQD rule has to validate the syntactical correctness of defined mandatory, regulatory required and optional BP data record attributes related to the specific regulations by the country authorized institutions. DQD furthermore has to rely on the following Standards: ISO 3166-1, ISO 20275, ISO 01-140-10, ISO 8601, ISO/IEC 8859-1. + +DQD has to visualize the outcome of the data quality rules via a dashboard. + +DQD uses the Gate API CX-0074_v3.0.0 and the Pool API CX-0012_v4.0.0 based on the CX-0018 Data Space Connectivity 3.0.0 +for pulling BP data records. DQD is a client/ server cloud application which contains a Web Client and a Cloud Server Application. + +DQD has to contain a user and authorization management capability aligned with the CX Portal and Marketplace user management. DQD intends to support the EDC Asset function capability and has to be available in English and German language. + +## FOR WHOM IS THE STANDARD DESIGNED + +The standard enables software and service companies to develop business partner master data quality dashboard applications including accessibility of external 3rd party data sources. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +| **Version** | **Publishing Date** | **Author** | **Description of Change** | +| ----------- | ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 1.1.0 | | SR | Added chapter 3 for DQD API. | +| 1.2.0 | 2024-03-13 | SR | Corrected 2.3.3 - country list, Added chapter 3.5 Data Types and 3.6 Data Attributes, Added chapter 3.7 for data sovereignty as additional requirement. | + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following audience: + +- Catena-X certified Operational Companies acting as: + - Core Service Provider + +This document is focusing on the functionality of the Data Quality Dashboard (DQD) as a screening and monitoring tool of CX Member business partner data in the Inbound Persistence based on the following capabilities: + +1. Data Profiling which is based on the analysis and evaluation of data content versus the CX business partner standards defined in CX-0076 Golden Record EndtoEnd Requirements Standard Version 1.1.0 +2. Visualization of BP data quality via a dashboard +3. Evaluation of the data quality results including recommendations for syntactical or logical error handling + +DQD has to be a Value Added Services (VAS) application for Data Provider and Consumer to monitor the data quality via a dashboard of BP data records in the Inbound Persistence. + +DQD rules have to be focused on the analysis of BP data record quality on a syntactical or content basis if possible. DQD does not focus on validating semantical correctness or data enrichment services. Those services are part of the Golden Record Process. + +The description of the Golden Record EndtoEnd Requirements Standard, the Gate API and the Pool API are stored in the standard library of Catena-X: https://catena-x.net/de/standard-library. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +The Data Quality Dashboard has to be a screening tool of the record process, rules, methodology and allocation of the BPN ID (Business Partner Number Identification) for Legal, Site and Address data records. DQD has to focus its validation and monitoring capabilities on all mandatory, regulatory required and optional business mission critical BP data record attributes to enable the CX Member to validate any impact on logistical, financially or communication relevant processes between the CX Member and his business partner. Furthermore, this transparency has to support the CX Member by improving his business partner related due diligence processes. The Data Quality Dashboard has to contain the capability to store the outcome of DQD results for at least 3 years and has to enable the definition of CX member specific data quality KPIs (Key Performance Indicator) and mapping against actual quality results. +DQD has to contain tiles which visualize the results with filter functions by time, region, country, BPN ID type, BP Roles, DQD status and business partner role. +~~ + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The keywords MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To prove conformity with this standard providing a self-audited, stated and signed document that the syntax of the number is established is needed. + +### 1.4 EXAMPLES + +Intentionally left blank + +### 1.5 TERMINOLOGY + +> *This section is normative* + +The main DQD rule methodologies are described below: + +#### Legal Form + +The DQD rules for legal form have to validate the correct usage of legal forms by the country list defined under Point 2.2. The rules have to rely on ISO 20275 (valid legal forms) in combination with ISO 3166-1 (valid country codes). The rules have to be based on the transliterated version and transliterated abbreviations of legal forms based on ISO 01-140-10. + +The DQD rules have to contain the capability to identify variations in the representation of legal forms by applying appropriate technologies to identify synonymous terms. +By missing terms via the ISO standards DQD has to complement the legal forms especially abbreviations as needed. + +#### Legal Name + +The DQD rules have to identify the correct Legal Name of a Legal Entity. This includes the capability to identify synonymous terms and abbreviations and convert them into the correct Legal Name as registered via authorized country registry. + +#### Tax Identification + +The DQD rules for tax identification have to be capable of validating the following Tax IDs by defined country and subregion: + +- Company Tax ID +- VAT ID +- Tax Jurisdiction Code + +The DQD rules for the **Company Tax Identification** have to validate the correct syntactical structure of the Company Tax ID defined by the related authorized country tax departments. +Additionally, to the Company Tax ID, DQD rules have to validate the syntactical correctness of the **VAT ID** by country. + +In selected countries a **Tax Jurisdiction Code** is required. The DQD rules have to validate the syntactical correctness by country. + +#### Address + +The DQD rules have to incorporate all specific country rules at a minimum as defined by the country list under Point 2.2 This includes the correctness of country, city by country, postal codes and optional the geographical coordinates based on ISO 6709 and WGS84 (World Geodetic System 1984). + +#### Relations + +The DQD rules have to validate the correctness of relations between the Legal, Site and Address entities as defined by the BP data model. + +#### Identifier + +To provide defined quality results of the DQD rules, they have to leverage publicly available BP Identifier to cross-check the correctness of BP data record attributes. + +## 2 MAIN CONTENT + +> *This section is normative* + +DQD has to contain the following dashboard-based functionalities: + +Visualization of Inbound Persistence BP data records by defined DQD rule results: + +1. Filter capabilities of BP data results by time, country, DQD status, BP role, DQD rule. +2. DQD rule statistics +3. BP data record statistics +4. Dashboard setting capabilities + +- NPM package: [https://www.npmjs.com/package/@catena-x/portal-shared-components/v/2.1.2](https://www.npmjs.com/package/@catena-x/portal-shared-components/v/2.1.2) +- Storybook: [https://eclipse-tractusx.github.io/portal-shared-components/](https://eclipse-tractusx.github.io/portal-shared-components/) + +The Data Quality Dashboard (DQD) MUST perform the validation of a BP data record which was uploaded into the CX Member Inbound Persistence. The DQD rule set and visualization of business partner data MUST be based at a minimum on the standards defined in CX-0010 Version 2.0.0 Business Partner Number, CX-0074 Version 3.0.0 Business Partner Gate API, CX-0012 Business Partner Pool API Version 4.0.0 include CX-0076 Version 1.1.0 Golden Record EndtoEnd Requirements Standard current versions or higher. + +### 2.1 Preconditions and Dependencies + +To run the DQD with the BPDM, Gate API and Pool API SHOULD be set up: https://github.com/eclipse-tractusx/bpdm/blob/main/README.md + +### 2.2 DQD Specifications + +The DQD rule set MUST use the following BP data record attributes +as defined in CX-0074 Version 3.0.0 or higher: + +1. Legal Entity which contains the following attributes + 1. External ID + 2. BPNL, BPNS, BPNA + 3. Legal Name Parts + 4. Legal Form + 5. Classifications + 6. Legal Address + 7. Created at + 8. Updated at +2. Legal Entity Identifier + 1. Value + 2. Type + 3. Issuing Body +3. Site +4. Address +5. Identifier Type + +### 2.3 DQD usage of Norms + +The DQD rule set MUST us the following ISO Norms: + +#### 2.3.1 ISO Norm 20275 + +The DQD rule set MUST use the content of the ISO 20275 to validate the correctness of legal names in long form and/or abbreviation in a transliterated form. + +[ISO 20275: Code-Liste für Rechtsträgerformen - GLEIF-Blogbeiträge - Newsroom & Medien – GLEIF](https://www.gleif.org/de/newsroom/blog/iso-20275-entity-legal-forms-code-list) + +#### 2.3.2 ISO Norm 3166-1 + +The DQD rule set** MUST use the ISO 3166-1 related codes for at least 116 countries as listed below: + +#### 2.3.3 Country List based on ISO 3166-1 + +|AD |CL |GE |IS |MC |PL |TJ | +| :- | :- | :- | :- | :- | :- | :- | +|AE |CN |GH |IT |MD |PT |TM | +|AL |CO |GI |JM |ME |PY |TN | +|AM |CR |GP |JP |MK |QA |TR | +|AR |CU |GR |KE |MT |RO |TT | +|AT |CY |GT |KG |MX |RS |TW | +|AU |CZ |HK |MY |RU |UA | +|AZ |DE |HN |KR |NA |SA |UK | +|BA |DK |HR |KW |NI |SE |US | +|BE |DZ |HT |KZ |NL |SG |UY | +|BG |EC |HU |LB |NO |SI |UZ | +|BO |EE |ID |LK |NZ |SK |VA | +|BR |EG |IE |LT |PA |SM |VE | +|BY |ES |IL |LU |PE |SN |VN | +|CA |FI |IN |LV |PH |SV |XK | +|CH |FR |IR |MA |PK |TH |ZA | +| | | | | | |ZW | + +[ISO - ISO 3166 — Country Codes](https://www.iso.org/iso-3166-country-codes.html) + +### 2.4 **DQD usage of External Data Sources** + +The DQD rule set might use defined external data sources supporting the rule set as needed in validating the correctness of CX Member business partner data records or providing recommendation of data enrichments. +The use of external data sources is dependent on the respective CX member as a user of DQD ensuring the provision of corresponding licenses through the respective API. Otherwise, DQD will only provide the results of the data quality screening for business partners in syntactic form. + +1. Commercial Register by defined countries based on ISO 3166-1 country list as defined in Chapter 2.3 +2. VAT ID provided by the European Tax Authorities or local tax authorities based on ISO 3166-1 country list as defined in Chapter 2.3 +3. Postal Code by country authorities +4. Legal Name and Legal Form owned by local authorities and based on ISO 20275 standard in long form and short form in transliterated version +5. Address details based on local authorities related to the country list based on 3166-2 as defined in Chapter 2.3 +6. GEO data based on WGS84 standard +7. Subregion Code based on ISO 3166-2 standard + +### 2.5 **DQD Results** + +The DQD rule set MUST provide for each BP data record a quality result based on a data field syntax check in the DQD Dashboard and in a DQD Logfile. + +### 2.6 **DQD Dashboard** + +The DQD Dashboard MUST provide the capabilities: + +1. Visualization of Business Partner Data records as defined by the Golden Record Process based on the CX-0076. +1. DQD provides visibility by defined user roles. They are mapped to the CX Portal user roles defined via the App Provider function. +1. DQD contains the visibility of BP data by user role and user based filter functions. The BP data can get filtered by: + 1. Year, quarter or month + 2. Country or Region as defined by ISO 3166-1 and ISO 3166-2 + 3. By BP type as customer or supplier + 4. By BP data record type BPNL, BPNS or BPNA as defined via CX-0010 Standard. +1. Visualization of Data Quality Screening results based on DQD KPIs and related achievements in percentage. This function enables the setting of BP data quality KPIs by CX Member +1. DQD contains a dark and light version option +1. DQD is available in German and English language +1. DQD contains a help function +1. DQD contains the capability to change layout and view setting by user +1. DQD contains an admin screen which enables user specific settings like layout and view settings, KPI target and threshold settings + +The DQD dashboard design relies on the Catena-X style guide. See details under: + +- Library: [https://www.npmjs.com/package/@catena-x/portal-shared-components](https://www.npmjs.com/package/@catena-x/portal-shared-components) +- Docu: [https://eclipse-tractusx.github.io/portal-shared-components/](https://eclipse-tractusx.github.io/portal-shared-components/) +- NPM package: [https://www.npmjs.com/package/@catena-x/portal-shared-components/v/2.1.2](https://www.npmjs.com/package/@catena-x/portal-shared-components/v/2.1.2) +- Storybook: [https://eclipse-tractusx.github.io/portal-shared-components/](https://eclipse-tractusx.github.io/portal-shared-components/) + +## 3.0 DQD API + +### 3.1 DQD Data Model + +The DQD Data Model as defined in the Annex chapter contains all BP and DQD dashboard attributes needed to perform +the DQD screening. The general length of a data attribute is 255 bytes. + +### 3.2 API Endpoints and Resources + +The resources MUST use the well-known HTTP request methods for CRU(D) operations: + +- POST MUST be used for create requests +- PUT MUST be used for update requests +- GET MUST be used for read requests + +POST MAY also be used for read requests, if input is not given by parameters but rather by an HTTP body to bypass maximum URL length. PUT MAY also be used for upsert requests (create or update) if this is required. A state (active / inactive) at each entity MUST be used for a soft delete, so that the request method DELETE SHALL NOT be used. Other HTTP request methods SHALL NOT be used, including PATCH. + +Uploading and downloading data to/from the DQD API MUST follow a staging concept with two stages, so that consumers of the DQD API can compare what they have uploaded into the input stage against what kind of DQD rule results and status code was provided for each business partner data in the output stage. The following controllers MUST distinguish between an input and an output stage. + +The DQD architecture describes in which intercommunication the DQD API is used. + +![image](https://github.com/catenax-eV/product-standardization-prod/assets/135617737/1e63720a-6414-4021-82ea-ee89b89ab8dc) + +### 3.3 **Data Quality Controller** + +The data quality controller MUST allow to create, update, or read (search / return) business partner data records related to an External Identifier or BPN ID in the input and output stage. It MUST have the following resources: + +|Business partner Data Controller Resources |Description | +| :-: | :-: | +|PUT/api/dqd/input/business partner data |Creates or updates shareholder data and 3rd party data related to business partner data record in the DQD database. | +|GET/api/dqd/output/DQD Screening Results|Returns DQD quality rule status codes from the DQD changelog by different search parameters | +|GET/api/dqd/output/DQD Statistics|Returns DQD quality statistics by different search parameters from the DQD changelog. | + +### 3.4. **Data Quality Sharing State Controller** + +The sharing state controller MUST allow to create, update, or read sharing state entries related to business partner data record DQD rule status codes.  The sharing state controller MUST have the following resources: + +|Sharing State Resources |Description | +| :-: | :-: | +|GET/api/dqd/sharing-state |Returns sharing states of business partner data filtered by legal name, legal form, External Identifier, BPN ID and type, country and status code | +|PUT/api/dqd/sharing-state |Creates or updates a sharing state of a business partner data record | + +### 3.5 **AVAILABLE DATA TYPES** + +The API **MUST** use JSON as the payload format transported via HTTP. Other formats can be added. These are then, however, **OPTIONAL**. + +### 3.6 **DATA ASSET STRUCTURE** + +The following data assets **MUST** be registered at the Core Service Provider so that the Sharing Member can negotiate an API usage contract with the Core Service Provider and access its dedicated BPDM Gate (hosted by the Core Service Provider) through these data assets[^6]: + +| **Name** | **Type** | **Version** | **Description** | +| ------------------------------------ | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| UploadAccessSharingMemberDataforDQD | DQD | 1.0 | Grants the Sharing Member full access to the DQD Admin function, DQD database and DQD changelog. This contains create / update DQD admin settings by Sharing Member role by DQD function, activating and deactivating the usage of external data sources via defined APIs and license keys. | +| UploadAccess3rdpartyDataforDQD | DQD | 1.0 | Grants the Sharing Member full access to upload 3rd party data for DQD rule execution| +| ReadAccessDQDOutputForSharingMember | DQD | 1.0 | Grants the Sharing Member read access of the DQD changelog. | +The OAuth2 client permissions **MUST** be configured to solely allow access to the API resources defined in the corresponding asset, checking HTTP method (read vs. full access), path, query parameters and body of the HTTP request. + +### 3.7 **ADDITIONAL REQUIREMENTS** + +#### 3.7.1 **CONVENTIONS FOR USE CASE POLICY IN CONTEXT OF DATA EXCHANGE** + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +#### 3.7.2 **ADDITIONAL DETAILS REGARDING ACCESS POLICIES** + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +#### 3.7.3 **ADDITIONAL DETAILS REGARDING USAGE POLICIES** + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +### **3.8 ERROR HANDLING** + +The following http response codes MUST be defined for all resources:   + +- 200 – OK   +- 400 – Bad Request +- 401 – Unauthorized +- 403 – Forbidden +- 404 – Not Found   +- 500 – Internal Server Error + +HTTP Status Code Registry MUST be adhered to in the implementation for the decision on when to use which error code: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml + +## 4 REFERENCES + +### 4.1 NORMATIVE REFERENCES + +[Business Partner Pool API](https://github.com/eclipse-tractusx/bpdm/tree/main/bpdm-pool-api/src/main/kotlin/org/eclipse/tractusx/bpdm/pool/api) + +[Business Partner Gate API](https://github.com/eclipse-tractusx/bpdm/tree/main/bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api) + +> ISO 3166-1 for referencing on country codes +> ISO 3166-2 for referencing on sub-region codes +> ISO 20275 for referencing on global valid legal forms +> ISO 6709 and World Geodetic Sytstem 1984 (WGS84) for referencing on Geo Data +> ISO 01-140-10 for transliteration of non-latin characters in to latin characters +> ISO 8601 for referencing to the international standard of the date format +> ISO/IEC 8859-1 for referencing to the International standard of the Multinational Character Set + +### 4.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +Intentionally left blank. + +[BPDM Catena-X Website](https://catena-x.net/en/offers-standards/bpdm) + +### 4.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Intentionally left blank. + +## ANNEXES + +### DQD Data Model + +| DQ Dashboard Data Model - Field name | Description | Type | +|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| Actual DQ KPI Percentage | The tile shows the actual data quality KPI of the sharing member in the persistence. The KPI takes the following DQ issues into account: ERRORS | Percentage | +| BP Type | BP type represents the BP types: Supplier, One Time Supplier, Customer, One Time Supplier, Business Partner as defined in the CX BP Data Model | Enum | +| BPN Issuing | A number which contains the CX Member BP data records which received a valid and unique BPN ID | Numeric | +| Business Partner Classification | The term contains the BP classification Legal, Site and Address | Enum | +| Country | Country represents the countries based on ISO 3166-1 | Alphanumeric | +| DQ KPI over Time Period | The chart shows the Target DQ KPI and the Actual DQ KPI values per month over the filtered time period as a line chart | Numeric | +| DQ Rules | Contain the total number of rules used to perform the screening process of business partner data | Numeric | +| DQ Status | DQ Status contains an array with all DQ status codes and reference to the appropriate DQ rules | Alphanumeric | +| DQ Target KPI CX Member Percentage | The tile shows the target data quality KPI of the sharing member in the persistence. The KPI can be defined by each sharing member individually (based on their own goals). | Percentage | +| Month | Defines a specific month | Alphanumeric | +| Number of Data Records | Contains the total number of BP master data in the CX Member Inbound Persistence, in the CX BP Pool and the number of overlapping BP data records | Numeric | +| PostalAddress.Country.CountryCode | Data field represents the country code as defined by ISO 3166-1 | Alphanumeric | +| PostalAddress.Country.Name | Country name represents the name based on ISO 3166-1 | Alphanumeric | +| Region | Region contains selected countries and subregions based on ISO 3166-1 and 3166-2 by the CX Member | String Array | +| Subregion | Subregions represents all subregions or dependent states based on ISO 3166-2 | Alphanumeric | +| Time period | The tile shows the time period for which the data records should be displayed and uses the data fields Year and Month. | Numeric | +| Total DQ Error Percentage | The tile shows the percentage value of all DQ errors of all BP data records of the sharing member in the persistence. | Percentage | +| Total DQ Errors | The tile shows the total number of DQ errors of all BP data records of the sharing member in the persistence. | Numeric | +| Total DQ Warning Percentage | The tile shows the percentage value of all DQ errors of all BP data records of the sharing member in the persistence. | Percentage | +| Total DQ Warnings | The tile shows the total number of DQ errors of all BP data records of the sharing member in the persistence. | Numeric | +| Year | Defines the selected year or duration of up to 3 years in the past | Numeric | + +### FIGURES + +> *This section is non-normative* + +Intentionally left blank. + +### TABLES + +> *This section is non-normative* + +Intentionally left blank. + +[^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf +[^2]: https://catena-x.net/de/standardisierung/catena-x-einfuehren-umsetzen/standardisierung/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0078-BankDataVerificationDashboard/CX-0078-BankDataVerificationDashboard.md b/docs/standards/CX-0078-BankDataVerificationDashboard/CX-0078-BankDataVerificationDashboard.md new file mode 100644 index 000000000..e242b790f --- /dev/null +++ b/docs/standards/CX-0078-BankDataVerificationDashboard/CX-0078-BankDataVerificationDashboard.md @@ -0,0 +1,354 @@ +# CX-0078 Bank Data Verification Dashboard v1.2.0 + +## ABSTRACT + +The Bank Data Verification Dashboard (BDV) has to rely on a set of clearly defined verification rules +which has to be the basis to verify the syntactical and logical correctness of banking details used by CX Member Business Partners. BDV has to capture at least 112 countries, states and dependent sub-regions based on ISO 3166-1 and 3166-2 - (see Point 2.3). BDV has to verify BP Banking data records provided by each CX Member. Each BDV rule has to verify the syntactical and logical correctness of defined banking data as defined via the BDV data and rule model. They represent the business mission critical banking data attributes for at least 125 countries. The BDV verification rules have to rely on standards defined by banking data related authorized organizations (European Payments Council for SEPA, European Committee for Banking Standards (ECBS) for IBAN based on ISO 13616, Society for Worldwide Interbank Financial Telecommunication +(S.W.I.F.T SC) for BIC Code based on ISO 9362. Additionally, BDV has to rely on national banking standards to complement global or regional standards related at least to the 116 countries as needed. BDV furthermore has to rely on the following Standards: ISO 3166-1, ISO 3166-2, ISO 20275, ISO 01-140-10, ISO 8601, ISO/IEC 8859-1. + +BDV has to visualize the outcome of the banking verification rules via a dashboard. There a user should be able to compare the input and output of banking data quality after the BDV verification process ended. + +BDV uses the Gate API CX-0074_v3.0.0 and the Pool API CX-0012_v4.0.0 based on the CX-0018 Data Space Connectivity 3.0.0 +for pulling BP data records for synchronization of CX Member BP data records with the CX Member banking data. The CX Member banking data has to be send via the BDV API. The results of the BDV verification have to be stored in the BDV Logfile and should get pulled via the BDV API from the CX Member systems. +BDV has to be a client/ server cloud application which has to contain a Web Client and a Cloud Servicer Application. +BDV has to contain a user and authorization management capability aligned with the CX Portal and Marketplace user management. BDV has to support the EDC Asset function capability and has to be available in English and German language. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +| **Version** | **Publishing Date** | **Description of Change** | +| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +|1.2.0 | 2024-03-24 | Corrected 2.3. - country list, Added chapter 3.4 Data Types and 3.5 Data Attributes, Added chapter 3.6 for data sovereignty as additional requirement. +1.2.0 | 2024-04-09 | Corrected 2.3. - Enhanced usage policies of BDV API | + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +*This section is non-normative.* + +This standard is relevant for the following audience: + +- Catena-X certified Operational Companies acting as: + - Core Service Provider + - Business Application Provider + - Data Provider and Consumer + +This document is focusing on the functionality of the Bank Data Verification Dashboard (BDV) as a screening and monitoring tool of banking data related quality. + +BDV has to be a Value Added Services (VAS) application for Data Provider and Consumer to verify the correctness of Banking Data provided by CX Member suppliers, customers or CpDs (Conto pro Diverse) in the role of a `One Time Customer` or `One Time Supplier`. + +BDV has to enrich the BP data model via a complementary banking data model. It has to contain a storage capability of statistical banking data quality outcome data over a time frame of at least 3 years. + +BDV rules have to focus on the verification of the banking data quality on a syntactical, logical or rule basis. BDV does not focus on validating semantical correctness or data enrichment services. + +BDV has to be able to use the Business Partner ID as described in CX-0010 Version 2.0.0 or higher documented in the standard library of Catena-X: https://catena-x.net/de/standard-library. +If used terms are not explicitly defined they rely on the standard definitions defined in the +upcoming Catena-X Business Partner Glossary. + +### 1.2 CONTEXT + +> *This section is non-normative* + +The Bank Data Verification Dashboard has to be the verification tool of CX Member bank data records. It has to support the validation of the correctness of banking related data provided by CX member suppliers, customers, `One Time Supplier`s and `One Time Customer`s. Furthermore, in combination with the Catena-X VAS solution Fraud Prevention it has to support the transparency if a banking data is affected by Fraud. BDV has to enable the management and monitoring of all CX member related banking details via a Dashboard and additionally the bi-directional intercommunication based on a BDV API. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +All sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To prove conformity with this standard providing a self-audited, stated and signed document that the syntax of the number is established is needed. + +### 1.4 TERMINOLOGY OF BANK DATA VERIFICATION DASHBOARD RULES + +> *This section is non-normative* + +The main BDV rule methodologies are described below: + +**IBAN – International Bank Account Number** +BDV has to validate the correctness of the IBAN in all defined SEPA countries based on the rules defined by the European Payments Council for SEPA and the European Committee for Banking Standards (ECBS) for IBAN based on ISO 13616. The Bank Account Number contains the individual account number, the routing number and the SWIFT Code of the bank. The verification is based on the ISO 3166-1 and ISO 3166-2 standards to secure that the BDV rule is correctly allocated to the appropriate countries and dependent states and regions as defined by the ISO norms. + +**BIC – Business Identifier Code** +BDV has to verify the correctness of the Business Identifier Code (BIC/SWIFT) of Financial Institutions. The Code is based on ISO 9362 defined by the Society for Worldwide Interbank Financial Telecommunication (S.W.I.F.T SC). The Code identifies an individual financial institution and the country residence based on the ISO 3166-1 and ISO 3166-2 standards to secure that the BDV rule is correctly allocated to the appropriate countries and dependent states and regions as defined by the ISO norms. + +**NBAN - National Bank Account Number** +BDV has to verify the correctness of the National Bank Account number as defined by the national bank institutions. This verification rule is based on the ISO 3166-1 and ISO 3166-2 standards to secure that the BDV rule is correctly allocated to the appropriate countries and dependent states and regions as defined by the ISO norms. + +**Business Partner** +BDV has to enable the transparency of the relation of a bank account to the appropriate business partner type as defined (Supplier, Customer, `One Time Supplier`, `One Time Customer`). + +**Fraud Case** +BDV with the support of the Fraud Prevention application has to verify if a bank account is affected by Fraud. This verification has to include the information of the Fraud status and timeframe of affection. + +**One time Customer and One time Supplier** +Business partners who have a business transaction with each other only once. + +### 1.6 OUT OF SCOPE + +The BDV product does not contain the functionality to correct and/or enrich a bank data record. + +### 1.7 BANK DATA VERIFICATION DASHBOARD + +BDV has to contain the following dashboard-based functionalities: + +1. Visualization of CX Member bank data verification results +2. Various bank data filter functionalities based on the bank data model +3. BDV target setting +4. Bank data record target versus actuals +5. Bank data rule results supported by dashboard visualization capabilities +6. Bank data visualization by country type +7. BDV statistical report +8. Search function +9. BDV dashboard settings by time, KPI, layout and view, country, language limited to German and English + +The results of BDV are accessible via a defined API and Changelog file managed via the Bank Data Sharing State Controller. + +The BDV dashboard design relies on the Catena-X style guide. Details via links below: +NPM package: https://www.npmjs.com/package/@catena-x/portal-shared-components/v/2.1.2 +Storybook: https://eclipse-tractusx.github.io/portal-shared-components/?path=/docs/chip--docs + +## 2 BANK DATA VERIFICATION DASHBOARD (NORMATIVE) + +The Bank Data Verification Dashboard (BDV) MUST perform the verification of a bank data record of a defined CX Member business partner. The BDV rule set and visualization of business partner data MUST be based on the standards defined in CX-0010 Version 2.0.0 Business Partner Number, CX-0074 Version 3.0.0 Business Partner Gate API, CX-0012 Business Partner Pool API Version 4.0.0 or higher. + +### 2.1 PRECONDITIONS AND DEPENDENCIES + +To run the BDV solution the BPDM, Gate API and Pool API SHOULD be set up: https://github.com/eclipse-tractusx/bpdm/blob/main/README.md + +### 2.2 BDV SPECIFICATIONS + +The BDV rule set MUST use the following BP data attributes: + +1. Legal Entity as defined by CX-0074 Version 3.0.0 which contains the following attributes + - External ID + - BPNL, BPNS, BPNA + - Legal Name Parts + - Legal Short Name + - Legal Form + - Classifications + - Legal Address + - Created at + - Updated at +2. Legal Entity Identifier as defined by CX-0074 Version 3.0.0 + - Value + - Type + - Issuing Body + +3. Site as defined by CX-0074 Version 3.0.0 +4. Address as defined by CX-0074 Version 3.0.0 +5. Identifier Type as defined by CX-0074 Version 3.0.0 + +### 2.3 BDV USAGE OF NORMS + +The BDV rule set MUST us the following ISO Norms: + +#### ISO 3166-1 Country + +The BDV rule set MUST use the ISO Norm 3166-1 related codes for at least 117 countries as listed below + +***Country List based on ISO 3166-1***   + +|AD |CL |GE |IS |MC |PL |TJ | +| - | - | - | - | - | - | - | +|AE |CN |GH |IT |MD |PT |TM | +|AL |CO |GI |JM |ME |PY |TN | +|AM |CR |GP |JP |MK |QA |TR | +|AR |CU |GR |KE |MT |RO |TT | +|AT |CY |GT |KG |MX |RS |TW | +|AU |CZ |HK |MY |RU |UA | +|AZ |DE |HN |KR |NA |SA |UK\* | +|BA |DK |HR |KW |NI |SE |US\*\* | +|BE |DZ |HT |KZ |NL |SG |UY | +|BG |EC |HU |LB |NO |SI |UZ | +|BO |EE |ID |LK |NZ |SK |VA | +|BR |EG |IE |LT |PA |SM |VE | +|BY |ES |IL |LU |PE |SN |VN | +|CA |FI |IN |LV |PH |SV |XK | +|CH\*\*\* |FR |IR |MA |PK |TH |ZA | +| | | | | | |ZW | + +[ISO - ISO 3166 — Country Codes](https://www.iso.org/iso-3166-country-codes.html) + +#### ISO 3166-2 Administrative Area (Level 1) + +The BDV rule set MUST use the ISO Norm 3166-2 related codes for administrative area (level 1) - country subdivision, such as regions within a country or dependent states. + +| Attribute | Description | (Data) Type / Code List / Enumeration | +| --- | --- | --- | +| Name | The name of the country subdivision according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). | String | +| Code | The six-character alphanumeric code according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), consisting of the two-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code and a three-character alphanumeric code for the subdivision in that country, separated by a hyphen. | String | + +#### ISO 13616 IBAN Number + +BDV MUST use the IBAN in all defined SEPA countries based on the rules defined by the European Payments Council for SEPA and the European Committee for Banking Standards (ECBS) for IBAN based on ISO 13616. + +#### ISO 9362 BIC – Business Identifier Code + +BDV MUST us the Business Identifier Code (BIC/SWIFT) of Financial Institutions. The Code is based on ISO 9362 defined by the Society for Worldwide Interbank Financial Telecommunication (S.W.I.F.T SC). The Code identifies an individual financial institution and the country residence based on the ISO 3166-1 and ISO 3166-2 standards to secure that the BDV rule is correctly allocated to the appropriate countries and dependent states and regions as defined by the ISO norms. + +**NBAN - National Bank Account Number** + +BDV MUST use the National Bank Account number as defined by the national bank institutions. This verification rule is based on the ISO 3166-1 and ISO 3166-2 standards to secure that the BDV rule is correctly allocated to the appropriate countries and dependent states and regions as defined by the ISO norms + +### 2.4 BDV USAGE OF EXTERNAL DATA SOURCES + +The BDV rule set MUST use defined external data sources supporting the rule set as needed in validating the correctness of bank data records or providing recommendations for data enrichments. External Data Sources are e.g. ISO 3166-1, ISO 3166-2, ISO 6074, SEPA, SWIFT, ISO 9362 and others. + +### 2.5 BDV RESULTS + +The BDV rule set MUST provide for each CX Member bank data record a result in the BDV dashboard and in the BDV Changelog file. + +### 2.6 BDV DASHBOARD + +The BDV Dashboard MUST provide the following results: + +Filter capabilities of BDV data results: + +1. By time (year, quarter, month) for rolling of 3 years at a minimum +2. By Business Partner Type +3. By Country +4. By Fraud Case Progress Status +5. By BDV Rule +6. By Status Code + +BDV MUST contain the following dashboard-based functionalities: + +1. Visualization of CX Member bank data verification results +2. Various bank data filter functionalities based on the bank data model +3. BDV target setting +4. Bank data record target versus actuals +5. Bank data rule results supported by dashboard visualization capabilities +6. Bank data visualization by country type +7. BDV statistical report +8. Search function +9. BDV dashboard settings by time, KPI, layout and view, country, language limited to German and English + +> The BDV dashboard design MUST use the Catena-X style guide. See details under confluence.catena-x.net/display/CORE/CX+Style+Guide + +## 3 BDV API + +### 3.1 API ENDPOINTS AND RESOURCES + +The resources MUST use the well-known HTTP request methods for CRU(D) operations: + +- POST MUST be used for create requests   +- PUT MUST be used for update requests   +- GET MUST be used for read requests   + +POST MAY also be used for read requests, if input is not given by parameters but rather by an HTTP body to bypass maximum URL length. PUT MAY also be used for upsert requests (create or update) if this is required. A state (active / inactive) at each entity MUST be used for a soft delete, so that the request method DELETE SHALL NOT be used. Other HTTP request methods SHALL NOT be used, including PATCH. + +Uploading and downloading data to/from the BDV API MUST follow a staging concept with two stages, so that consumers of the BDV API can compare what they have uploaded into the input stage against what kind of BDV rule results and status code was provided for each bank data in the output stage. The following controllers MUST distinguish between an input and an output stage. + +Data Sovereignty: The BDV API allows to upload CX Member banking details related to business partner master data and the download of banking data related quality results of related business partner data in a data sovereign way, because each Catena-X member has its own area of business partner data in BPDM, where private data (like customer / supplier relationships) is only visible to the Catena-X member. + +The BDV rule set might use defined external data sources supporting the rule set as needed in validating the correctness of bank data records or providing recommendations for data enrichments. External Data Sources are e.g. ISO 3166-1, ISO 3166-2, ISO 6074, SEPA, SWIFT, ISO 9362 and others. External data sources will only get used if the CX Member using BDV will provide appropriate licenses by API to access external data sources. + +### 3.2 BANK DATA CONTROLLER + +The bank data controller MUST allow to create, update, or read (search / return) bank data records related to an External Identifier or BPN ID in the input and output stage. It MUST have the following resources: + +|Bank Data Controller Resources |Description | +| :-: | :-: | +|PUT/api/bdv/input/bank data |Creates bank data record or updates existing bank data record in the input stage. | +|GET/api/bdv/output/bank data record|Returns bank data record from the output stage by different search parameters | +|GET/api/bdv/input/bank data records|Returns bank data record rule status codes by different search parameters from the BDV changelog. | + +### 3.3 BANK DATA SHARING STATE CONTROLLER + +The sharing state controller MUST allow to create, update, or read sharing state entries of bank data records.  The sharing state controller MUST have the following resources: + +|Sharing State Resources |Description | +| :-: | :-: | +|GET/api/bdv/sharing-state |Returns sharing states of bank data filtered by IBAN, BIC, NBAN, External Identifier, BPN ID and type, country and status code | +|PUT/api/bdv/sharing-state |Creates or updates a sharing state of a bank data record | + +### 3.4 AVAILABLE DATA TYPES + +The API **MUST** use JSON as the payload format transported via HTTP. Other formats can be added. These are then, however, **OPTIONAL**. + +### 3.5 DATA ASSET STRUCTURE + +The following data assets **MUST** be registered at the Core Service Provider so that the Sharing Member can negotiate an API usage contract with the Core Service Provider and access its dedicated BPDM Gate (hosted by the Core Service Provider) through these data assets [^6]: + +| **Name** | **Type** | **Version** | **Description** | +| ------------------------------------ | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FullAccessBDVInputOutputForSharingMember | BDV | 1.0 | Grants the Sharing Member full access to the BDV Admin function, BDV database and BDV changelog. This can be used for create and update of banking data records, to read banking data record rule status in the BDV changelog, create / update DQD admin settings by Sharing Member role by BDV function, activate and deactivate the usage of external data sources via defined APIs and license keys. | +| ReadAccessDQDOutputForSharingMember | BDV | 1.0 | Grants the Sharing Member read access of the BDV changelog, banking data records, BDV rule result statistics. | + +The OAuth2 client permissions **MUST** be configured to solely allow access to the API resources defined in the corresponding asset, checking HTTP method (read vs. full access), path, query parameters and body of the HTTP request. + +### 3.6 ADDITIONAL REQUIREMENTS + +#### 3.6.1 CONVENTIONS FOR USE CASE POLICY IN CONTEXT OF DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps + +#### 3.6.2 ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +#### 3.6.3 ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +### 3.7 ERROR HANDLING + +The following http response codes MUST be defined for all resources:   + +- 200 – OK   +- 400 – Bad Request +- 401 – Unauthorized +- 403 – Forbidden +- 404 – Not Found   +- 500 – Internal Server Error + +HTTP Status Code Registry MUST be adhered to in the implementation for the decision on when to use which error code: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml + +## 4 REFERENCES + +### 4.1 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +[BPDM Catena-X Website](https://catena-x.net/en/offers-standards/bpdm) + +### 4.2 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +[Business Partner Pool API](https://github.com/eclipse-tractusx/bpdm/tree/main/bpdm-pool-api/src/main/kotlin/org/eclipse/tractusx/bpdm/pool/api) + +[Business Partner Gate API](https://github.com/eclipse-tractusx/bpdm/tree/main/bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api) + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +Intentionally left blank. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0079-NaturalPersonScreeningDashboard/CX-0079-NaturalPersonScreeningDashboard.md b/docs/standards/CX-0079-NaturalPersonScreeningDashboard/CX-0079-NaturalPersonScreeningDashboard.md new file mode 100644 index 000000000..381fe7603 --- /dev/null +++ b/docs/standards/CX-0079-NaturalPersonScreeningDashboard/CX-0079-NaturalPersonScreeningDashboard.md @@ -0,0 +1,473 @@ +# CX-0079 Natural Person Screening Dashboard v1.2.0 + +## ABSTRACT + +![image](./assets/299394830-48b494f3-1b8e-4cf2-8c33-62c249f24eff.png) + +- In view of the fact that Catena-X cannot manage Natural Persons it has to be secured that no Natural Person by accident may be processed or later stored in the pool. + +![image](./assets/299395649-448eb834-071d-4dbb-8c1c-f36af2308f08.png) + +- For historical reasons, companies often have no knowledge of whether the stored Business Partner master record contains a Natural Person. For example, there is a way to change this master record as Natural Person, but this has often not been done consistently in the past. + +- In addition, the companies themselves need knowledge of Natural Persons in their systems to comply with GDPR requirements. + +The Natural Person Screening application contains rules which secure with a high probability to identify Natural Person data records. The results of the rules can be visualized via a dashboard or consumed via logfiles as well as downloaded via an API. NPS uses the Gate API CX-0074_v3.0.0 and the Pool API CX-0012_v4.0.0 based on the CX-0018 Data Space Connectivity 3.0.0 for pulling BP data records. +NPS is a client/ server cloud application which contains a Web Client and a Cloud Servicer Application. +NPS has to contain a user and authorization management capability aligned with the CX Portal and Marketplace user management. NPS has to be available in English and German language. + +## FOR WHOM IS THE STANDARD DESIGNED + +The standard enables software and service companies to develop business partner master data quality dashboard applications including accessibility of external 3^rd^ party data sources. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +| **Version** | **Publishing Date** | **Description of Change** | +| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 1.1.0 | | Added chapter 3 for NPS API. | +| 1.2.0 | 2024-03-24 | Corrected 2.3 - country list, Added chapter 3.6 Data Types and 3.7 Data Attributes, Added chapter 3.8 for data sovereignty as additional requirement. | + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following audience: + +- Catena-X certified Operational Companies acting as: + - Core Service Provider + +This document is focusing on the functionality of the Natural Person Screening Dashboard (NPS) as a screening and monitoring tool of the Golden Record process. NPS rules focus on the analysis of the BP data records on a syntactical and partially semantical content basis. NPS will not focus on correcting or enriching data attributes services. Those services are part of the Golden Record Process. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +The Natural Person Screening Dashboard is a screening tool and methodology to identify automated with a high probability if a BP data record in the Inbound Persistence is a Natural Person or a Legal Entity. The results of the validation have to be provided via a dashboard. + +The description of the required Gate API CX-0074, Version 3.0.0 is accessible throug the standard library of Catena-X: https://catena-x.net/de/standard-library + +> Data Sovereignty: The NPS API allows to download natural person screening related quality results of related business partner data in a data sovereign way, because each Catena-X member has its own area of business partner data in BPDM, where private data (like customer / supplier relationships) is only visible to the Catena-X member. + +https://datatracker.ietf.org/doc/html/bcp14 + +https://www.w3.org/TR/did-core/ + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +*This section is non-normative.* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The keywords **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +All participants will need to prove that their solutions conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To prove conformity with the standard, verify your implementation aligns with the following sharing controller. + +[https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml](https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml) + +### 1.4 EXAMPLES + +Intentionally left blank + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +**Natural Person** +A Natural Person is a person that is an individual human being. + +**Legal Person** +A Legal Person is a Legal Entity as defined in CX-0010. + +The Natural Person Screening Dashboard (NPS) has to rely on a set of clearly defined screening rules which are the basis the validate if a Business Partner (BP) is a Natural Person or a Legal Entity. NPS has to capture at least 112 countries based on ISO 3166-1. NPS has to validate BP data records in the Inbound Persistence of the related CX Member who licensed NPS. Each NPS rule has to validate defined attributes of the BP data record via a specific rule set. The architecture of NPS has to based on an exclusion methodology. The outcome of NPS has to provide results if a BP data record is a Natural Person, a Legal Entity or an undefined, unknown or unable to locate person based on the data content and quality provided. + +The outcome of the main NPS rule methodologies are described below: + +### 1.6 Identifier Check + +NPS has to validate if the BP data record in the Inbound Persistence is already a valid +Golden Record data record with a valid BPN ID. + +### 1.7 Locality Check + +NPS has to validate the locality of the BP data record as a basis for further screening methodologies. + +### 1.8 Identification Check + +NPS has to validate the given Identifier about their formal correctness and use the content of the Identifier via the NPS rule set to identify a Legal or a Non-Legal Entity. + +### 1.9 Check via External Data Sources + +NPS has to match BP data entries with appropriate global data sources to identify Natural Persons or Legal Entities. + +### 1.10 Legal Form Check + +NPS has to validate any Legal Form indicators of the BP data record against country specific company and institutional valid organizational forms. + +### 1.11 Final Natural Person Identifier Check + +NPS has to validate the BP data records against Natural Person Identifiers on a global basis. + +### 1.12 Inbound Persistence + +The Inbound Persistence contains the BP data records which were send by a CX Member for +validation and screening via the Gate API as defined in CX-0074 Version 3.0.0. + +## 2 MAIN CONTENT + +> *This section is normative* + +NPS has to be a Value Added Services (VAS) application for Data Provider and Consumer to screen all BP data records in the Inbound Persistence to find a Natural Person data record. NPS has to contain a screening capability which enables that no Natural Person data record will get passed into the Golden Record Process as the process handles solely Legal Entity data records. + +NPS has to contain the storage capability of statistical data over a time frame of at least 3 years. + +NPS has to contain the following dashboard-based functionalities: + +Visualization of BP data records by defined NPS screening methodologies: + +Filter capabilities of BP data results + +1. By time (year, quarter, month) for rolling 3 years at a minimum +2. By NPS validation classification (Natural Person, Legal Entity, Undefined) +3. By Country +4. By Status Code (Red, Yellow, Green) +5. BP data record detailed with NPS rule results + +Number of rules used +Search function and scrollbars +Number of data records validated by NPS + +NPS has to rely on the Catena-X style guide. +See details under + +- NPM package: https://www.npmjs.com/package/@catena-x/portal-shared-components/v/2.1.2 +- Storybook: https://eclipse-tractusx.github.io/portal-shared-components/?path=/docs/chip--docs + +NPS has to contain an administration screen with the following functionalities + +1. User Role definition and allocation +2. Regional settings +3. Country and Subregion settings +4. Notification settings +5. Layout and View settings + +There is the intent that the results of NPS have to be accessible via a logfile of each CX Member. + +The NPS dashboard design relies on the Catena-X style guide. See details under: +Open-Source Repository: https://github.com/eclipse-tractusx/portal-shared-components + +NPM package: https://www.npmjs.com/package/@catena-x/portal-shared-components/v/2.1.2 + +Storybook: https://eclipse-tractusx.github.io/portal-shared-components/?path=/docs/chip--docs + +The Natural Person Screening (NPS) MUST perform the validation if a BP data record which was uploaded into the Inbound Persistence is a Natural Person that is an individual human being, or a Legal Entity based as defined in CX-0010 Version 2.0.0 or higher. To perform the Natural Person Screening rules, NPS MUST use the Gate API as defined in CX-0074 Version 1.1.0 or higher which MUST be implemented based on the OpenAPI 3.0.1 specification or higher. + +### 2.1 Preconditions and Dependencies + +To run the NPS the BPDM, Gate API and Pool API SHOULD be set up: https://github.com/eclipse-tractusx/bpdm/blob/main/README.md + +### 2.2 NPS Specifications + +The NPS rule set MUST use the following BP data record attributes +based on the CX-0074 Version 3.0.0 or higher: + +1. Legal Entity which contains the following attributes +2. External ID +3. BPNL +4. Legal Name Parts +5. Legal Form +6. Classifications +7. Legal Address +8. Created at +9. Updated at +10. Legal Entity Identifier +11. Value +12. Type +13. Issuing Body3. Site +14. Address +15. Identifier Type +16. Changelog Entry +17. Identifier Array (Commercial Registry, Company Tax ID, VAT ID, Tax Jurisdiction Code, +DUNS) + +### 2.3 NPS usage of Norms + +The NPS rule set MUST use the following ISO Norms: + +**ISO 20275** +**The NPS rule set MUST use the content of the ISO Norm 20275 to validate the correctness of legal names in long form and/or abbreviation in a transliterated form. + +[ISO 20275: Code-Liste für Rechtsträgerformen - GLEIF-Blogbeiträge - Newsroom & Medien -- GLEIF] + +**ISO 3166-1** +The NPS rule set MUST use the ISO Norm 3166-1 related codes for at least 112 countries as listed below + +**Country List based on ISO 3166-1** +| | | | | | | | +| :- | :- | :- | :- | :- | :- | :- | +|AD |CL |GE |IS |MC |PL |TJ | +|AE |CN |GH |IT |MD |PT |TM | +|AL |CO |GI |JM |ME |PY |TN | +|AM |CR |GP |JP |MK |QA |TR | +|AR |CU |GR |KE |MT |RO |TT | +|AT |CY |GT |KG |MX |RS |TW | +|AU |CZ |HK |MY |RU |UA | +|AZ |DE |HN |KR |NA |SA |UK | +|BA |DK |HR |KW |NI |SE |US | +|BE |DZ |HT |KZ |NL |SG |UY | +|BG |EC |HU |LB |NO |SI |UZ | +|BO |EE |ID |LK |NZ |SK |VA | +|BR |EG |IE |LT |PA |SM |VE | +|BY |ES |IL |LU |PE |SN |VN | +|CA |FI |IN |LV |PH |SV |XK | +|CH |FR |IR |MA |PK |TH |ZA | +| | | | | | |ZW | + +[ISO - ISO 3166 --- Country Codes] + +### 2.4 NPS usage of External Data sources + +The NPS rule set might use defined external data sources supporting the identification of a Natural Person or Legal Entity using a Natural First and Last Name. The usage of external data sources and related APIs is dependent on the licenses provided by the CX Member as user of NPS. + +### 2.5 NPS Results + +The NPS rule set MUST provide for each CX Member business partner data record in the Inbound Persistence a result in the NPS Dashboard. + +### 2.6 NPS Dashboard + +The NPS Dashboard MUST provide the following results: + +Visualization of BP data records based on defined NPS screening methodologies: + +Filter capabilities of BP data results + +1. By time (year, quarter, month) for the duration of up to 3 years into the past +2. By NPS validation classification (Natural Person, Legal Entity, Undefined) +3. By Country +4. By Error Code Status (Red, Yellow, Green) +5. BP Data record detailed with NPS rule results +6. Number of rules used +7. Search function and scrollbars +8. Number of data records validated by NPS + +The NPS Dashboard Admin Screen MUST provide the following capabilities: + +1. User Role definition and allocation +2. Regional settings +3. Country settings +4. Notification settings +5. Layout and View settings + +NPS has to rely on the Catena-X style guide. +See details under + +- Library: https://www.npmjs.com/package/@catena-x/portal-shared-components +- Docu: https://eclipse-tractusx.github.io/portal-shared-components/?path=/docs/chip--docs +- NPM package: https://www.npmjs.com/package/@catena-x/portal-shared-components/v/2.1.2 +- Storybook: https://eclipse-tractusx.github.io/portal-shared-components/?path=/docs/chip--docs + +## 3.0 NPS API + +### 3.1 NPS Architecture + +![image](https://github.com/catenax-eV/product-standardization-prod/assets/135617737/52f861d1-8c55-42de-9ad4-043c012e85cf) + +The NPS Architecure defines the usage of the NPS API. It secures the intercommuncation between a user and the NPS application to i.e. consume the NPS results out of the NPS logfile. + +### 3.2 API Endpoints and Resources + +The resources MUST use the well-known HTTP request methods for CRU(D) operations: + +- POST MUST be used for create requests +- PUT MUST be used for update requests +- GET MUST be used for read requests + +POST MAY also be used for read requests, if input is not given by parameters but rather by an HTTP body to bypass maximum URL length. PUT MAY also be used for upsert requests (create or update) if this is required. A state (active / inactive) at each entity MUST be used for a soft delete, so that the request method DELETE SHALL NOT be used. Other HTTP request methods SHALL NOT be used, including PATCH. + +Uploading and downloading data to/from the NPS API MUST follow a staging concept with two stages, so that consumers of the NPS API can compare what they have uploaded into the input stage against what kind of NPS rule results and status code was provided for each business partner data in the output stage. The following controllers MUST distinguish between an input and an output stage. + +### 3.3 NPS Data Model + +The NPS data model as detailed in the Annex chapter defines all Business Partner data attributes which are needed that NPS can perform the defined screening rules. Furthermore it contains all attributes the NPS dashboard requires to publish the NPS screening results. + +### 3.4 Natural Person Controller + +The natural person controller MUST allow to create, update, or read (search / return) business partner data records related to an External Identifier or BPN ID in the input and output stage. It MUST have the following resources: + +| Business partner Data Controller Resources  | Description  | +| - | - | +| PUT/api/nps/input/business partner data  | Creates business partner data record or updates existing business partner data record in the input stage. | +| GET/api/nps/output/business partner record | Returns business partner data record from the output stage by different search parameters. | +| GET/api/nps/input/business partner records | Returns business partner data record by different search parameters from the input stage. | + +### 3.5 Natural Person Sharing State Controller + +The sharing state controller MUST allow to create, update, or read sharing state entries of business partner data records.  The sharing state controller MUST have the following resources: + +| Sharing State Resources | Description | +| - | - | +| GET/api/nps/sharing-state | Returns sharing states of business partner data filtered by natural person flag, legal name, legal form, External Identifier, address, BPN ID and type, country and status code | +| PUT/api/nps/sharing-state | Creates or updates a sharing state of a business partner data record | + +Each NPS rule creates results which can get accessed via a NPS changlog containing defined status codes by rule + +### 3.6 **Available Data Types** + +The API **MUST** use JSON as the payload format transported via HTTP. Other formats can be added. These are then, however, **OPTIONAL**. + +### 3.7 **Data Asset Structure** + +The following data assets **MUST** be registered at the Core Service Provider so that the Sharing Member can negotiate an API usage contract with the Core Service Provider and access its dedicated BPDM Gate (hosted by the Core Service Provider) through these data assets[^6]: + +| **Name** | **Type** | **Version** | **Description** | +| ------------------------------------ | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FullAccessNPSInputOutputForSharingMember | NPS | 1.0 | Grants the Sharing Member full access to the NPS Admin function, NPS database and NPS changelog. This can be used to read business partner NPS rule status in the NPS changelog, create / update NPS admin settings by Sharing Member role by NPS function, activate and deactivate the usage of external data sourves via defined APIs and license keys. | +| ReadAccessNPSOutputForSharingMember | NPS | 1.0 | Grants the Sharing Member read access of the NPS changelog. | +The OAuth2 client permissions **MUST** be configured to solely allow access to the API resources defined in the corresponding asset, checking HTTP method (read vs. full access), path, query parameters and body of the HTTP request. + +### 3.8 **ADDITIONAL REQUIREMENTS** + +#### 3.8.1 **CONVENTIONS FOR USE CASE POLICY IN CONTEXT OF DATA EXCHANGE** + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +#### 3.8.2 **ADDITIONAL DETAILS REGARDING ACCESS POLICIES** + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +#### 3.8.3 **ADDITIONAL DETAILS REGARDING USAGE POLICIES** + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +### **3.9 ERROR HANDLING** + +The following http response codes MUST be defined for all resources:   + +- 200 – OK   +- 400 – Bad Request +- 401 – Unauthorized +- 403 – Forbidden +- 404 – Not Found   +- 500 – Internal Server Error + +HTTP Status Code Registry MUST be adhered to in the implementation for the decision on when to use which error code: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml + +## 4 REFERENCES + +### 4.1 NORMATIVE REFERENCES + +[Business Partner Pool API](https://github.com/eclipse-tractusx/bpdm/tree/main/bpdm-pool-api/src/main/kotlin/org/eclipse/tractusx/bpdm/pool/api) + +[Business Partner Gate API](https://github.com/eclipse-tractusx/bpdm/tree/main/bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api) + +CX-0018 Eclipse Data Space Connector (EDC), Version 2.1.0 + +ISO 3166-1 for referencing to the country codes +ISO 20275 for referencing to the globally valid legal forms + +### 4.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +[BPDM Catena-X Website](https://catena-x.net/en/offers-standards/bpdm) + +### 4.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Intentionally left blank. + +## ANNEXES + +### NPS Data Model + +| NPS BP Data Model | Description | Type | +|------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------| +| Legal Entity BPN | Unique Identification of a legal entity | Alphanumeric | +| Legal Form | Valid Lagel Form content based on ISO 20275 | Alphanumeric | +| Site BPN | Unique Identification of a Site location of a defined legal entity | Alphanumeric | +| Legal Entity External Identifier | Unique Identifier of a business partner data record of a specific CX Member | Alphanumeric | +| Site External Identifier | Unique Identifier of a site business partner data record of a specific CX Member | Alphanumeric | +| Identifier | An array of unique official identifier from grovernmantel organisations or 3rd party data provider | Enum | +| Legal Entity Roles (Customer, Supplier) | An array of defined business partner roles like supplier, customer, one time supplier, one time customer of business partner | Enum | +| Legal Name Parts | The complete name of a business partner including the legal form which could based on the length needs multiple name part fields | String Array | +| Country | Country is represented by the ISO 3166-1 country code | Alphanumeric String (2 Bytes) | +| Region | Region is field which enables each CX Member to summarize multiple countries to one regional area | Enum | +| IsLegal Address | Represents the relationship between a legal entity and their related address | Boolean | +| Street | Represents the offical street name of the entity | String Array | +| Postal Address (Postal Code, City) | Represents the official addess of the entity | String (Array) | +| Longitude | Represents the official part of the GEO data based on WGS84 | Float | +| Latitude | Represents the official part of the GEO data based on WGS84 | Float | +| Altitude | Represents the official part of the GEO data based on WGS84 | Float | +| | | | +| NPS Dashboard Data Model | | | +| Total BP Records Pool | Represents the active BP data records in the CX BP Pool | Numeric | +| Total Legal BP Records Pool | Represents the active Legal BP data records in the CX BP Pool containing a BPNL ID | Numeric | +| Total Site BP Records Pool | Represents the active Site BP data records in the CX BP Pool containing a BPNS ID | Numeric | +| Total Address BP Records Pool | Represents the active Address BP data records in the CX BP Pool containing a BPNA ID | Numeric | +| Total BP Records CX Member | Represents the active BP data records in the CX BP Pool of the CX Member using the NPS solution | Numeric | +| Total Legal BP Records CX Member | Represents the active legal BP data records in the CX Inbound Persistence of the CX Member using the NPS solution | Numeric | +| Total Site BP Records CX Member | Represents the active site BP data records in the CX Inbound Persistence of the CX Member using the NPS solution | Numeric | +| Total Address BP Records CX Member | Represents the active address BP data records in the CX Inbound Persistence of the CX Member using the NPS solution | Numeric | +| Total BP Records Overlap | Represents the number of how many different CX Members are using the same business partner data record | Numeric | +| Total Legal BP Records Overlap | Represents the number of how many different CX Members are using the same legal business partner data record | Numeric | +| Total Site BP Records Overlap | Represents the number of how many different CX Members are using the same site business partner data record | Numeric | +| Total Address BP Records Overlap | Represents the number of how many different CX Members are using the same site address partner data record | Numeric | +| Implemented Rule Set | Defines the number of NPS rules used by the NPS application | Numeric | +| White List | Defines company names by using a natural person name being a legal entity | String Array | +| Black List | Defines a list of natural persons which are no legal entity and indentified via the NPS rukes | String Array | +| NPS Dashboard Result Date | Defines the date by which a NPS screening result was performed | Numeric | +| Total Number Natural Persons (L,S,A) | Defines the number of natural persons found by performing NPS | Numeric Array | +| Total Number Natural Persons (L,S,A) | Defines the percentage of natural persons found by performing NPS in relation to the total number of BP data records of the CX Member | Percentage Array | +| Total Number No Natural Persons (L,S,A) | Defines the number of non-natural persons found by performing NPS | Numeric Array | +| Total Number No Natural Persons (L,S,A) | Defines the percentage of non-natural persons found by performing NPS in related to the total number of BP data records of the CX Member | Percentage Array | +| Total Number Natural Persons - Supplier (L,S,A) | Defines the number of natural persons found by performing NPS on the BP type - supplier | Numeric Array | +| Total Number Natural Persons - Supplier Undefined (L,S,A) | Defines the number of natural persons found by performing NPS on the BP type - supplier undefined | Numeric Array | +| Total Number Natural Persons - Customer (L,S,A) | Defines the number of natural persons found by performing NPS on the BP type - customer | Numeric Array | +| Total Number Natural Persons - Customer Undefined (L,S,A) | Defines the number of natural persons found by performing NPS on the BP type - customer undefined | Numeric Array | +| Hit Score | Defines a percentage how many hits were found against total number of BP data records of a CX Member | Percentage Array | +| Traffic Light Marker ( Red, Yellow, Green) | Visualize the NPS results by category allocated by the color red, yellow and green | String Array | +| Warning Text | Contains for each NPS rule a text result category warning | String | +| Error | Contains for each NPS rule a text result category error | String Array | +| Help Text | Contains the user manual and help text components to guide the user how to use NPS | String | +| User Settings | The user setting enables individual customization of NPS dashboard functionalities and content | Enum | +| Legal Form White List incl. Synonymous terms | Contains a list of natural persons acting as legal entities which are valid and variations of the name | Table | +| Legal Form Black List incl. Synonymous terms | Contains a list of natural persons acting as legal entities by error and variations of the name | Table | +| Synonymous Table Legal Form long version | Contains variations of legal forms | Table | +| Synonymous Table Legal Form Abbreviations | Contains variations of legal form abbreviations | Table | + +### FIGURES + +> *This section is non-normative* + +Intentionally left blank. + +### TABLES + +> *This section is non-normative* + +Intentionally left blank. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0079-NaturalPersonScreeningDashboard/assets/299394830-48b494f3-1b8e-4cf2-8c33-62c249f24eff.png b/docs/standards/CX-0079-NaturalPersonScreeningDashboard/assets/299394830-48b494f3-1b8e-4cf2-8c33-62c249f24eff.png new file mode 100644 index 000000000..1e82e6dc6 Binary files /dev/null and b/docs/standards/CX-0079-NaturalPersonScreeningDashboard/assets/299394830-48b494f3-1b8e-4cf2-8c33-62c249f24eff.png differ diff --git a/docs/standards/CX-0079-NaturalPersonScreeningDashboard/assets/299395649-448eb834-071d-4dbb-8c1c-f36af2308f08.png b/docs/standards/CX-0079-NaturalPersonScreeningDashboard/assets/299395649-448eb834-071d-4dbb-8c1c-f36af2308f08.png new file mode 100644 index 000000000..28b874a2a Binary files /dev/null and b/docs/standards/CX-0079-NaturalPersonScreeningDashboard/assets/299395649-448eb834-071d-4dbb-8c1c-f36af2308f08.png differ diff --git a/docs/standards/CX-0080-BPDMFraudPreventionService/CX-0080-BPDMFraudPreventionService.md b/docs/standards/CX-0080-BPDMFraudPreventionService/CX-0080-BPDMFraudPreventionService.md new file mode 100644 index 000000000..8e008a357 --- /dev/null +++ b/docs/standards/CX-0080-BPDMFraudPreventionService/CX-0080-BPDMFraudPreventionService.md @@ -0,0 +1,318 @@ +# CX-0080 BPDM Fraud Prevention Service v1.1.0 + +## ABSTRACT + +Digital fraud risks are constantly increasing, e.g., in the form of fake invoices sent in the name of real suppliers, but with third-party (fraudster) account data. +The Fraud Prevention Service provides information on most recent fraud cases which have been shared within the Catena-X (CX) network by contributing companies. +It therefore benefits from the overall idea of data sharing within the Catena-X community as such information is nowhere available in any data source accessible along the automotive supply chain. + +There is a strong need to create such a reliable data source by anonymously sharing fraud details within the CX member network. + +This data shall be made accessible and consumable via dashboard & reporting functionalities. + +By using this information, the CX community has the chance to prevent fraud cases in their own companies as they can use shared data about e.g., fraudulent bank accounts to stop payments and so avoid financial losses and reputation damage. + +The purpose of this standard is to describe guidelines and requirements specific for the challenges of fraud risks in order to minimize such threats and implications for the own company. It focuses on fraudulent bank data as the most common fraud type although other relevant fraud types are also considered. + +## FOR WHOM IS THE STANDARD DESIGNED + +This standard is designed for Business Application Provider. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +| **Version** | **Publishing Date** | **Description of Change** | +| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +|1.1.0 | 2024-03-13 | Updated to template v2.0.0. Added chapter 2.6 Data Types and 2.8 Data Attributes, Added chapter 2.7 for data sovereignty as additional requirement. + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following audience: + +- Catena-X certified Operational Companies acting as: + - Business Application Provider + - Data Provider and Consumer + +This document focuses on the requirements regarding provision of fraud data and getting access to such data via reporting- / dashboard functionalities. + +It is relevant for business application providers who want to provide services for collecting, aggregating and reporting fraud data by empowering the CX companies to provide such data in an easy but formalized, secure and anonymous way. + +It is also relevant for data providers and consumers as it is initially the CX community who acts as data provider and consumer itself and can be extended with other communities or data providers. + +> Data Sovereignty: The FPS API allows to download DQD quality results of business partner data in a data sovereign way, because each Catena-X member has its own area of business partner data in BPDM, where private data (like customer / supplier relationships) is only visible to the Catena-X member. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +Fraud prevention service (FPS) is a value-added service (VAS) in the area of Business Partner Data Management which addresses the challenges for a company in terms of legal, compliance- and finance-related requirements. + +FPS has to visualize the outcome of the fraud prevention screening results via a dashboard. + +FPS uses the Gate API CX-0074_v3.0.0 and the Pool API CX-0012_v4.0.0 based on the CX-0018 Data Space Connectivity 3.0.0 +for pulling BP data records. FPS is a client/ server cloud application which contains a Web Client and a Cloud Server Application. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +All sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To prove conformity with this standard providing a self-audited, stated and signed document that the syntax of the number is established is needed. + +### 1.4 EXAMPLES + +N/A + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +| Term | Description | +| :- | :- | +|Fraud Case Type|Describes the type of fraud case, e.g., active warning, fake bank data change or falsified Invoice. | +|Confirmation State|Specifies whether a fraud case is confirmed or not. | +|Date of Attack|Specifies the date of the attack. | +|Description|Some explanation and background to a fraud case.| +|International Bank Account Identifier (IBAN)|IBAN as to be defined by the European Payments Council for SEPA, European Committee for Banking Standards (ECBS) for IBAN based on ISO 13616| +|Business Identifier Code (BIC)|This field contains the BIC code according to ISO 9362 and is also known as SWIFT-BIC, SWIFT ID, or SWIFT code, after the Society for Worldwide Interbank Financial Telecommunication (SWIFT), which is designated by ISO as the BIC registration authority (SWIFT).| +|Country Code|Country the bank account is present respectively where the fraud case has occurred. Country Code as defined in ISO 3166-1 | +|Region or State Code|Code represents the region or dependent state as defined in ISO 3166-2| +|National Bank Account Number (NBAN)|National Bank Account Number| +|Bank Name|Name of the bank | +|Fraudster Email|Email the fraudster used to communicate with the affected company| +|Fraudster Phone |Phone the fraudster used to communicate with the affected company| + +The Fraud Prevention Service has to provide at a minimum the following results: + +| Term | Description | +| :- | :- | +|Reporting Data and Time|Specifies the date and time the fraud case was reported.| +|Reporting Organization|Specifies the organization that reported the fraud case. So, the organization that submitted the fraud case in the CX system.| +|Internal ID |Sequential and unique number to identify the fraud case.| +|Frequency|Numeric field how often the fraud case was confirmed e.g., by using the same IBAN-no.| +|Fraud Case Counter|Total no. of reported fraud cases within this service| + +## 2 MAIN CONTENT + +> *This section is normative* + +The Fraud Prevention Service (FPS) is a reporting and monitoring solution and MUST provide the following capabilities as minimum requirement: + +1\. Fraud case reporting: + +- User interface for unified reporting of fraud cases, integrated in the Fraud Prevention Dashboard (FPD) +- Template for entering fraud data by the CX member +- Individual selection of different fraud case types and status +- Anonymized distribution of fraud cases to an aggregated CX fraud case database as basis for dashboard display (although the information about the fraud case originator MUST be retrievable by the service provider for e.g., audit reasons) + +2\. Dashboard functions: + +- Administration functionality + - Switch between languages (MUST: German and English, others optional) + - User information (name, corresponding CX-registered organization) based on CX-role and authorization management + - Export / Download function for dashboard content (including graphical reports) +- Selection functionality + - Individual selection of fraud case types (including multi-selection) + - Individual selection of time periods of interest +- Display functionality + - Graphical reports: + - Graphical reports MUST reflect the chosen time period as well as the selected fraud case types + - The reports MUST illustrate the following: + - CX-Fraud case distribution per country (with figures) + - Number of CX-reported fraud cases over time per fraud case type + - List report: + - The list report MUST contain all CX-reported fraud cases + - There MUST be filter and sort functions for the list content in order to focus on e.g., relevant time periods, fraud case types or countries + - There MUST be a search function for a content look-up like IBAN-Number. (if provided in the reported fraud cases) + - There MUST be an export function for the list report in a common standard format + +The Fraud Prevention Service has to contain the following functionalities: + +- Getting informed about most recent fraud cases reported by CX members +- Selecting different fraud types and time ranges +- Discovering trends and conspicuities by using graphical front ends +- Searching the CX fraud database for different values/strings, e.g., IBAN +- Retrieving fraud case details with sort- & filter functions +- Reporting new fraud cases directly out of the dashboard +- Exporting in different formats and on different levels + +### 2.1 FRAUD PREVENTION SERVICE DATA ATTRIBUTES + +The Fraud Prevention Service API MUST contain at least the following data attributes: + +|Fraud Case Type|Describes the type of Fraud Case, e.g., active warning, fake bank data change or falsified Invoice. | +| :- | :- | +|Confirmation State|Specifies whether a fraud case is confirmed or not. | +|Date of Attack|Specifies the date of the attack. | +|Description|Some explanation and background to a fraud case.| +|International Bank Account Identifier (IBAN)|IBAN number as to be defined by the European Payments Council for SEPA, European Committee for Banking Standards (ECBS) for IBAN based on ISO 13616| +|Business Identifier Code (BIC)|This field contains the BIC code according to ISO 9362 and is also known as SWIFT-BIC, SWIFT ID, or SWIFT code, after the Society for Worldwide Interbank Financial Telecommunication (SWIFT), which is designated by ISO as the BIC registration authority (SWIFT).| +|Country Code|Country the bank account is present respectively where the fraud case has occurred. Country Code as defined in ISO 3166-1| +|Region or State Code|Code represents the region or dependent state as defined in ISO 3166-2| +|National Bank Account Number (NBAN)|National Bank Account Number| +|Bank Name|Name of the bank | + +### 2.2 API ENDPOINTS AND RESOURCES + +The resources MUST use the well-known HTTP request methods for CRU(D) operations: + +- POST MUST be used for create requests   +- PUT MUST be used for update requests   +- GET MUST be used for read requests   + +POST MAY also be used for read requests, if input is not given by parameters but rather by an HTTP body to bypass maximum URL length. PUT MAY also be used for upsert requests (create or update) if this is required. A state (active / inactive) at each entity MUST be used for a soft delete, so that the request method DELETE SHALL NOT be used. Other HTTP request methods SHALL NOT be used, including PATCH. + +Uploading and downloading data to/from the FPD API MUST follow a staging concept with two stages, so that consumers of the FPD API can compare what they have uploaded into the input stage against what kind of BDV rule results and status code was provided for each bank data in the output stage. The following controllers MUST distinguish between an input and an output stage. + +The resources MUST use the HTTP request methods for READ operations: + +- GET MUST be used for read requests + +### 2.3 FRAUD PREVENTION API DATA ATTRIBUTES + +The Fraud Prevention Dashboard API MUST support requests for the following data attributes or combinations of these for read operations: + +|Fraud Prevention Service API Data Fields |Format| +| :- | :- | +|IBAN|Alphanumeric String| +|BIC/SWIFT|Alphanumeric String| +|NBAN|Alphanumeric String| +|Bank Name|Alphanumeric String| +|Country Code|2-digit alphanumeric string| +|Region or State Code|6-digit alphanumeric string| +|Confirmation State|Enum | +|Date of Attack |Date format| +|Fraud Case Counter|Numeric| +|Fraud Case Type|Enum| + +### 2.4 Fraud Prevention DATA CONTROLLER + +The fraud prevention data controller MUST allow to create, update, or read (search / return) i.e. bank data records related to an External Identifier or BPN ID. It MUST have the following resources: + +|Fraud Prevention Data Controller Resources |Description | +| :-: | :-: | +|PUT/api/fpd/input/bank data |Creates bank data record or updates existing bank data record. | +|GET/api/fpd/output/bank data record|Returns bank data record by different search parameters. | +|GET/api/fpd/input/bank data records|Returns bank data record by different search parameters. | + +### 2.5 Fraud Prevention DATA SHARING STATE CONTROLLER + +The sharing state controller MUST allow to create, update, or read sharing state entries of bank data records.  The sharing state controller MUST have the following resources: + +|Sharing State Resources |Description | +| :-: | :-: | +|GET/api/fpd/sharing-state |Returns sharing states of bank data filtered by IBAN, BIC, NBAN, External Identifier, BPN ID and type, country, fraud status code | +|PUT/api/fpd/sharing-state |Creates or updates a sharing state of a bank data record | + +### 2.6 AVAILABLE DATA TYPES + +The API **MUST** use JSON as the payload format transported via HTTP. Other formats can be added. These are then, however, **OPTIONAL**. + +### 2.7 DATA ASSET STRUCTURE + +The following data assets **MUST** be registered at the Core Service Provider so that the Sharing Member can negotiate an API usage contract with the Core Service Provider and access its dedicated BPDM Gate (hosted by the Core Service Provider) through these data assets[^6]: + +| **Name** | **Type** | **Version** | **Description** | +| ------------------------------------ | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| UploadAccessForSharingMember | FPD | 1.0 | Grants the Sharing Member full access to the FPD Admin function, FPD database and FPD changelog. This contains create / update FPD admin settings by Sharing Member role by FPD function, activate and deactivate the usage of external data sources via defined APIs and license keys. | +| UploadBankingDataAccessForSharingMember | FPD | 1.0 | Grants the Sharing Member full access to create / update Banking data records from Sharing Member| +| ReadAccessFPDOutputForSharingMember | FPD | 1.0 | Grants the Sharing Member read access of the FPD changelog. | +The OAuth2 client permissions **MUST** be configured to solely allow access to the API resources defined in the corresponding asset, checking HTTP method (read vs. full access), path, query parameters and body of the HTTP request. + +### 2.8 ADDITIONAL REQUIREMENTS + +#### 2.8.1 CONVENTIONS FOR USE CASE POLICY IN CONTEXT OF DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +#### 2.8.2 ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +#### 2.8.3 ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +### 2.9 ERROR HANDLING + +The following http response codes MUST be defined for all resources: + +- 200 – OK +- 400 – Bad Request +- 401 – Unauthorized +- 403 – Forbidden +- 404 – Not Found +- 500 – Internal Server Error + +HTTP Status Code Registry MUST be adhered to in the implementation for the decision on when to use which error code: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml + +## 3 REFERENCES + +### **3.1 NORMATIVE REFERENCES** + +> *This section is normative* + +- The country codes and the country names used in FPD MUST comply with ISO 3166-1. +- The Region or State Codes used in FPD MUST comply with ISO 3166-2. + +### **3.2 NON-NORMATIVE REFERENCES** + +> *This section is non-normative* + +- [BPDM Catena-X Website](https://catena-x.net/en/offers-standards/bpdm) + +- The Fraud Prevention Dashboard design relies on the Catena-X style guide. +- The Business Identifier Code (BIC) provided in the fraud reporting template shall be according to ISO 9362. +- The International Bank Account Number provided in the fraud reporting template shall be according to ISO 13616. + +[^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf +[^2]: https://catena-x.net/de/standardisierung/catena-x-einfuehren-umsetzen/standardisierung/standard-library + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +Not applicable. + +### TABLES + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0081-BPDMCountryRisk/CX-0081-BPDMCountryRisk.md b/docs/standards/CX-0081-BPDMCountryRisk/CX-0081-BPDMCountryRisk.md new file mode 100644 index 000000000..bf8335816 --- /dev/null +++ b/docs/standards/CX-0081-BPDMCountryRisk/CX-0081-BPDMCountryRisk.md @@ -0,0 +1,474 @@ +# CX-0081 Country Risk API v1.2.0 + +## ABSTRACT + +The Country Risk Application is a Value-Added Service (VAS) to the Catena-X ecosystem and is meant to assess country specific risks. To accomplish this, the application collects data from ratings, which create country specific scores ranging from 0–100. Which ratings and sources are used is the responsibility of the respective service provider submitting said datasets. These ratings are then mapped to business partners which are collected from sharing member specific sources, namely the Business Partner GATE, to ensure not to mix data between sharing members. A sharing member can display and download its mapped information in a dashboard or receive the information via API calls to use the information in its own systems. + +The user can create and upload their own ratings as well and assign country specific values depending on their own research. The country is then classified depending on the user's uploaded rating data. The scope of this document is to describe the dedicated API for this application, for collecting the necessary data from sharing members, as well as how to share the mapped data with them. + +This document is to be read in context with the other relevant Catena-X standards. In addition, it assumes that the relevant entities have followed and met all the other dependent onboarding processes and requirements. + +You can find the [Gate Standard as CX - 0074 Business Partner Gate API](https://catena-x.net/de/standard-library) and other standards in the standard library of Catena-X: [https://catena-x.net/de/standard-library](https://catena-x.net/de/standard-library) + +## FOR WHOM IS THE STANDARD DESIGNED + +This document is mainly targeted to technical individuals involved in integrating and developing against this API, as well as business individuals who are involved in the compliance process of this API. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +| Version | Description | Date | Author | +|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------| ------------------------------------------------------------- | +| V1.0.0 | Initial release | 06.10.2023 | Enzio Lincke, Fábio Mota, Alexander Keppler, Korbinian Hutter | +| V1.1.0 | Update regarding generic endpoint of the Gate and the Tractus-X EDC. Affected chapters are [1.2.1.4 The Generic Endpoint](#1214-the-generic-endpoint) & [2.2.3 EDC DATA ASSET STRUCTURE](#223-data-asset-structure) | 22.03.2024 | Fábio Mota, Alexander Keppler | +| V1.2.0 | Update on data asset and added new context for Country Risk. Added new section for Additional Requirements. Affected chapters are [2.2.3 DATA ASSET STRUCTURE](#223-data-asset-structure) & [2.2.5 ADDITIONAL REQUIREMENTS](#225-additional-requirements) | 20.06.2024 | Fábio Mota, Alexander Keppler | + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +*This section is non-normative.* + +The purpose of this standard is to improve interoperability and provide a standardized solution for the Catena-X network. This standard is relevant for Catena-X certified Operational Companies acting as Business Application Providers. This document focuses on the Country Risk application and its respective API. The API is the base framework for the Country Risk Dashboard, as the front-end dashboard uses API calls to receive relevant data. Country Risk is a VAS of Catena-X and is part of the “Know Your Business Partner”-approach and the business partner Golden Record process. + +This standard is relevant for the following roles. + +- Data Provider / Consumer +- Business Application Provider + +The API as currently implemented consists of two distinct sections, which are listed and referred to as the dashboard and sharing controllers. The dashboard controller implementation is OPTIONAL and not in the scope of this standard. The sharing controller is REQUIRED, and therefore is part of the scope of this standard. The standard is only relevant when a Business Application Provider wishes to obtain certification by Catena-X to offer a Catena-X certified Country Risk application. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +*This section is non-normative.* + +Geopolitical risks are becoming increasingly relevant in today's VUCA (Volatile, Uncertain, Complex, Ambiguous) environment, and businesses require effective solutions to meet their needs. VUCA times are characterized by rapid changes, such as wars, shortages, and political instabilities to name a few. + +The key business challenge is to maintain timely awareness of a business partner's status, whether during ongoing business or during the initial stages of partnership development. Businesses need to know who they are dealing with, particularly when engaging in international partnerships. + +The country risk score gives insights into country-specific information related to corruption, political stability, economic risk, and social and structural factors. + +There are several challenges that exist when it comes to conducting risk assessments. + +- Data is not updated frequently, which means that risk assessments are usually conducted only once a year, leaving assessments dependent on outdated or incorrect information. +- Most risk assessments are still being conducted manually or with semi-automated processes, leading to a greater likelihood of errors. +- Risk assessments are often derived from only a few sources and, as a result, the coverage can be incomplete and not as comprehensive as needed. Not all business partners are considered due to limitations in the amount of time and resources required. +- Extraordinary events are analysed reactively and manually, requiring considerable time and effort. +- With a large system landscape, it is often not possible to perform a direct check of all business partners, and manual data consolidation must take place. +- Finally, manual reconciliation can be error-prone, resulting in potential inaccuracies in the overall risk assessment results. + +The below diagram outlines the interaction of the components of the Country Risk application, API and other external objects. + +![StandardisedDataExchange](./assets/StandardisedDataExchange.png) + +In the below diagram, the two types of access mediums are shown for front-end and back-end access and application usage. + +![access mediums](./assets/access-mediums.jpeg) + +There is a reference implementation for the Country Risk API on GitHub. It is part of a Spring Boot Java open-source software project under the hood of the Eclipse Foundation and follows the Apache 2.0 licenses. + +For the complete and up-to-date API setup refer to the following website: https://github.com/eclipse-tractusx/vas-country-risk + +For an architecture overview refer to the ARC42 documentation: https://github.com/eclipse-tractusx/vas-country-risk/blob/release/v1.3.1/docs/Arc42-Documentation.md + +To use the BPDM Gate API in the Country Risk use case apart from this standard, the following other standards should be considered by all participants for which this standard is relevant: + +- CX-0018 Dataspace Connectivity +- CX-0074 Business Partner Gate API + +You can find the other standards in the standard library of Catena-X: [https://catena-x.net/de/standard-library](https://catena-x.net/de/standard-library). + +### 1.2.1 BUSINESS PARTNER NUMBER (BPN) AND RATING MAPPING LOGIC TO OBTAIN RATING DATA + +The Country Risk Application needs to comply with the three different business partner types as per the data model, namely these are: + +- Legal Entity +- Site +- Address + +Based on this statement, the following data needs to be received from the sharing member’s Business Partner Gate. + +#### 1.2.1.1 LEGAL ENTITY + +| Attribute | Description | Data Type | +| ------------ | ----------------------------------------------------------------- | --------- | +| BPNL | The identifier of the data set issued by BPDM | String | +| Legal name | The legal name of the company | String | +| Street name | The name of street of the address of this business partner | String | +| House number | The number assigned to the property in a street | Integer | +| Postal Code | The postal code of an area | String | +| City | The name of the city from the address of this business partner | String | +| Country | The name of the country from the address of this business partner | String | +| Longitude | GPS Coordinates in decimal degrees notation. | Float | +| Latitude | GPS Coordinates in decimal degrees notation. | Float | + +#### 1.2.1.2 SITE + +| Attribute | Description | Data Type | +| ------------ | ----------------------------------------------------------------- | --------- | +| BPNS | The identifier of the data set issued by BPN Issuer | String | +| Legal name | The legal name of the company | String | +| Street name | The name of the street address of the business partner | String | +| House number | The number assigned to a property in a street | Integer | +| Postal Code | The postal code of an area | String | +| City | The name of the city from the address of this business partner | String | +| Country | The name of the country from the address of this business partner | String | +| Longitude | GPS Coordinates in decimal degrees notation. | Float | +| Latitude | GPS Coordinates in decimal degrees notation. | Float | + +#### 1.2.1.3 ADDRESS + +| Attribute | Description | Data Type | +| ------------ | ----------------------------------------------------------------- | --------- | +| BPNA | The identifier of the data set issued by BPDM | String | +| Legal name | The legal name of the company | String | +| Street name | The name of street of the address of the business partner | String | +| House number | The number assigned to the house in a street | Integer | +| Postal Code | The postal code of an area | String | +| City | The name of the city from the address of this business partner | String | +| Country | The name of the country from the address of this business partner | String | +| Longitude | GPS Coordinates in decimal degrees notation. | Float | +| Latitude | GPS Coordinates in decimal degrees notation. | Float | + +#### 1.2.1.4 The Generic Endpoint + +At the heart of our data acquisition is the Generic Endpoint, a feature of the BPDM Business Partner Gate Api. +This endpoint is engineered to provide a comprehensive stream of data, encompassing the various aspects of business partner information that are crucial for our risk assessment procedures. + +**Key Functions of the Generic Endpoint:** + +- **Data Aggregation**: It compiles information from multiple types, offering a centralized view of business partner data. +- **Real-Time Updates**: The endpoint ensures that the information is current, reflecting the latest changes and developments. +- **Accessibility**: Designed for ease of use, the Generic Endpoint allows for seamless integration with the existing systems and processes around the golden record process. +- **Comprehensive Data Mapping**: The data provided by the Generic Endpoint is meticulously mapped to the fields of the three business partner types discussed earlier: Legal Entity, Site, and Address. This ensures a coherent and comprehensive data integration, reflecting the data across these distinct yet interconnected categories. + +Each piece of information sourced from the Generic Endpoint is carefully aligned with the corresponding attributes of Legal Entity, Site, and Address. This alignment facilitates a uniform and accurate representation of data, contributing significantly to the integrity and reliability of risk assessment processes. The data mapping adheres strictly to the structure and requirements laid out in the previous sections, ensuring consistency and precision in our risk evaluation methodologies. + +This endpoints role is integral to maintaining the accuracy and reliability of our risk assessments, ensuring that decisions are made based on the most current and complete information available. + +### **1.3 CONFORMANCE AND PROOF OF CONFORMITY** + +*This section is non-normative.* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The keywords **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +All participants will need to prove that their solutions conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To prove conformity with the standard, verify your implementation aligns with the following sharing controller. + +[https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml](https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml) + +### 1.4 EXAMPLES + +*This section is non-normative.* + +Intentionally left blank. + +### 1.5 TERMINOLOGY + +*This section is non-normative.* + +[Mandatory] The following terms are especially relevant for the understanding of the standard: + +- Business Partner Number (BPN): A BPN is the unique identifier of a business partner within Catena-X. There are 3 types of BPNs. +- BPNL: A BPNL represents and uniquely identifies a legal entity, which is defined by its legal name (including legal form, if registered), legal address and tax number. +- BPNS: A BPNS represents and uniquely identifies a site, which is where for example a production plant, a warehouse, or an office building is located. +- BPNA: A BPNA represents and uniquely identifies an address, which can be the legal address of a legal entity, and/or the main address of a site, or any additional address of a legal entity or site (such as different gates). +- BPDM Gate: The Gate is the entry point for each sharing member who exchanges BPDM data with a core service provider. For each sharing member an individual gate is set up. Any bi-directional intercommunication between the sharing member and the BPDM services is handled via the gate. The interoperability with the gate is enabled via a set of APIs. The usage of the gate APIs requires the Tractus-X EDC connector functionalities. +- VAS: Value-Added Service, an additional feature or capability of a core platform. +- Rating: A score provided by an entity regarding the performance of another entity. In the context of this API standard, it is the performance of a given metric of a Business Partner or Country relating to a certain standard. An example might be 2021 CPI of India being X.Y%. + +## 2 COUNTRY RISK API + +*This section is normative.* + +The Country Risk API allows business partners to acquire and represent data records and their respective country risk scores according to the selected ratings. The Country Risk API MUST be implemented based on the [OpenAPI 3.0.1 specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md). + +The API documentation can be found in the following directory and file. It is RECOMMENDED to review the API documentation. + +[https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml](https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml) + +### **2.1 PRECONDITIONS AND DEPENDENCIES** + +*This section is non-normative.* + +To integrate and connect to the API the following documentation should be reviewed. + +For the Country Risk API and database: https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/README.md + +For the Country Risk Dashboard:https://github.com/eclipse-tractusx/vas-country-risk/blob/main/README.md + +A dependency of this specification is that the user has subscribed to a Golden Record solution of a core service provider, and has an operational gate implemented. The Business Partner Gate standard must be implemented as per the following standard: +CX-0074 Business Partner Gate API + +### 2.2 API SPECIFICATION + +*This section is normative.* + +The Country Risk API has no rate limit imposed. Users are RECOMMENDED to implement the necessary monitoring on their infrastructure to log performance metrics, and to facilitate the diagnostics of future support issues. + +#### 2.2.1 API ENDPOINTS & RESOURCES + +The Country Risk API MUST be implemented as defined in the following OpenAPI document: + +[https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml](https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml) + +The resources MUST use the well-known HTTP request methods for CRU(D) operations: + +- POST MUST be used for create requests. +- PUT MUST be used for update requests. +- GET MUST be used for read requests. + +POST MAY also be used for read requests, if input is not given by parameters but rather by an HTTP body to bypass maximum URL length. PUT MAY also be used for upsert requests (create or update) if this is required. A state (active / inactive) at each entity MUST be used for a soft delete, so that the request method DELETE SHALL NOT be used. Other HTTP request methods SHALL NOT be used, including PATCH. + +To facilitate the compliance assessment, this chapter additionally lists and describes the API resources of the Country Risk API per API controller. + +The following API controllers of the OpenAPI document MUST be implemented: + +- [Sharing Controller](https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml) + +##### 2.2.1.1 DASHBOARD CONTROLLER + +*This section is non-normative.* + +The Dashboard Controller allows the Country Risk application to represent data on the front-end user dashboard. For the purpose of this standard, the Dashboard Controller calls are optional. + +The API calls listed under the Dashboard Controller are more numerous and beyond the scope of M2M automation and integration, hence are not covered in this document. The full global API consisting of the Dashboard and Sharing Controller can be found below. + +[https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/dashboard_controller.yml](https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/dashboard_controller.yml) + +##### 2.2.1.2 SHARING CONTROLLER + +The Sharing Controller MUST allow the user to read (search / return) information about the sharing members and their business partners. + +It MUST have the following resources: + +| Sharing Controller Resources | Description | +| --------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| GET/api/sharing/getAllRatingsScoresForEachBpn | Retrieves Mapped ratings to the Business Partners based on inserted year, Company User, Ratings and BPN. | +| GET/api/sharing/getAllRatingsForCompany | Retrieves ratings based on inserted year and Company user. | + +###### 2.2.1.2.1 ESTABLISHING AVAILABLE RATING DATA + +To get a list of all available ratings for the desired year, the following endpoint must be called. + +> GET/api/sharing/getAllRatingsForCompany + +Input Data Example: + +| Attribute | Description | Data Type | +| --------- | -------------------------------------------------------- | --------- | +| year | The year of the publication of the corresponding rating. | Integer | + +Output Data Example: + +| Attribute | Example Output | Description | +| -------------- | ------------------- | -------------------------------------------------------------------------------------------------- | +| dataSourceName | Test Rating | Source name of the rating being referenced. | +| type | Custom | Indicates view permissions as; global; company (company of sharing member) and custom (user only). | +| yearPublished | 2021 | Corresponding year of the rating. | +| fileName | Test Company Rating | Reference to the uploaded rating file. | + +###### 2.2.1.2.2 ESTABLISHING RATINGS FOR BPNS + +In order to get a list of ratings for specific BPNs available to the sharing member, the following endpoint has to be called. + +> GET/api/sharing/getAllRatingsScoresForEachBpn + +Input Data Example: + +| Attribute | Description | Data Type | +| --------- | ---------------------------------------------------------------------------- | --------- | +| ratings | A pair of rating name and year, per rating. Can parse multiple rating pairs. | string | +| bpn | One or multiple BPNs, including their respective country. | string | + +The below image is an example which represents multiple BPNs being entered in the mentioned GET call. + +![Input Data Example](./assets/InputDataExample.png) + +Output Data Example: + +| Attribute | Description | Data Type | +| -------------- | ---------------------------------------------------------------------------- | --------- | +| bpn | One or multiple BPNs. | string | +| country | Indicates the country of the listed BPN. | string | +| iso2 | Indicates the ISO3166-1 alpha-2 code of the country. | string | +| ratings | A pair of rating name and year, per rating. Can parse multiple rating pairs. | string | +| dataSourceName | Source name of the rating being referenced, per rating, if multiple. | string | +| score | The score provided by the rating, per rating, if multiple. | float | +| yearPublished | The year of the rating, per rating, if multiple. | float | + +The below image is an example which represents multiple ratings being returned per BPN. + +![Output Data Example](./assets/OutputDataExample.png) + +#### 2.2.2 AVAILABLE DATA TYPES + +The API MUST use JSON as the payload format transported via HTTP. Other formats can be added. These are then, however, OPTIONAL. + +#### 2.2.3 DATA ASSET STRUCTURE + +The following data asset MUST be registered at the Core Service Provider so that the Sharing Member can negotiate an API usage contract with the Core Service Provider and access its dedicated services: + +| **Name** | **Type** | **Version** | **Description** | +|-------------------------------------------|----------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| FullAccessCountryRiskSharingForVASUser | CountryRisk | 1.3.1 | Grants unrestricted access to business partner data for the Data Consumer of the Country Risk Dashboard and Sharing API. This includes data identified via BPN and enriched from the pool. It allows the use of risk categorizations from various indices within the data consumer's company. Data usage is covered by the framework agreement for the gate. | + +For each read resource in the Sharing Country Risk API there MUST be a dedicated Data asset definition. + +Example data asset: + +```json +{ + "@context": { + "dct": "https://purl.org/dc/terms/", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "cx-common": "https://w3id.org/catenax/ontology/common#", + }, + "@type": "Asset", + "@id": "e94272b1-9831-458f-8986-c63c4973ea60", + "properties": { + "dct:type": { + "@id": "cx-taxo:CountryRisk" + }, + "cx-common:name": { + "@id": "cx-taxo:FullAccessCountryRiskSharingForVASUser" + }, + "cx-common:version": "1.3.1", + "cx-common:description": "Grants unrestricted access to business partner data for the Data Consumer of the Country Risk Dashboard and Sharing API. This includes data identified via BPN and enriched from the pool. It allows the use of risk categorizations from various indices within the data consumer's company. Data usage is covered by the framework agreement for the gate." + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "https:///api/sharing", + "oauth2:tokenUrl": "https:///auth/realms//protocol/openid-connect/token", + "oauth2:clientId": "", + "oauth2:clientSecretKey": "", + "proxyMethod": true, + "proxyPath": true, + "proxyQueryParams": true, + "proxyBody": true + } +} +``` + +The OAuth2 client permissions MUST be configured to solely allow access to the API resources defined in the corresponding asset, checking HTTP method, path, query parameters and body of the HTTP request sent to the data plane public API which acts as a proxy for the Country Risk API. + +#### 2.2.4 ERROR HANDLING + +The IANA HTTP Status Code Registry MUST be adhered to in the implementation for the decision on when to use which error code: + +[https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) + +The following HTTP response codes MUST be defined for all resources: + +| Code | Description | +| ---- | --------------------- | +| 200 | OK | +| 400 | Bad Request | +| 401 | Unauthorised | +| 403 | Forbidden | +| 404 | Not Found | +| 500 | Internal Server Error | + +### 2.2.5 ADDITIONAL REQUIREMENTS + +#### 2.2.5.1 CONVENTIONS FOR USE CASE POLICY IN CONTEXT OF DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +##### 2.2.5.2 ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +##### 2.2.5.3 ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +## 3 REFERENCES + +*This section is non-normative.* + +- ISO3166-1: The international standard for country codes and codes for their subdivisions. + +### 3.1 NORMATIVE REFERENCES + +Intentionally left blank. + +### 3.2 NON-NORMATIVE REFERENCES + +*This section is non-normative.* + +The below link includes further information on the API and is optional. + +[https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml](https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml) + +The below link includes background information on BPDM and the Value-Added Service Ecosystem. + +[https://catena-x.net/en/offers-standards/bpdm](https://catena-x.net/en/offers-standards/bpdm) + +The following link is regarding the BPDM Gate API. + +[Business Partner Gate API](https://github.com/eclipse-tractusx/bpdm/tree/main/bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api) + +### 3.3 REFERENCE IMPLEMENTATIONS + +*This section is non-normative.* + +There is a reference implementation for Country Risk APIs on GitHub. It is part of a Java Spring Boot open-source software project under the hood of the Eclipse Foundation and is distributed under the Apache 2.0 license. + +The complete and up-to-date setup guide to implement the standard can be found below. + +For API and database: + +https://github.com/eclipse-tractusx/vas-country-risk-backend + +For front-end Dashboard: + +https://github.com/eclipse-tractusx/vas-country-risk + +The below link references the source code of the back end of the application. + +https://github.com/eclipse-tractusx/vas-country-risk-backend/tree/main/src/main/java/org/eclipse/tractusx/valueaddedservice/web/rest + +The below link references the source code of the front-end (dashboard) of the application. + +https://github.com/eclipse-tractusx/vas-country-risk/tree/main/src/components + +## ANNEXES + +Reserved for future use. + +## FIGURES + +*This section is non-normative.* + +Reserved for future use. + +## TABLES + +*This section is non-normative.* + +Reserved for future use. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0081-BPDMCountryRisk/assets/InputDataExample.png b/docs/standards/CX-0081-BPDMCountryRisk/assets/InputDataExample.png new file mode 100644 index 000000000..d9f8ca3c6 Binary files /dev/null and b/docs/standards/CX-0081-BPDMCountryRisk/assets/InputDataExample.png differ diff --git a/docs/standards/CX-0081-BPDMCountryRisk/assets/OutputDataExample.png b/docs/standards/CX-0081-BPDMCountryRisk/assets/OutputDataExample.png new file mode 100644 index 000000000..c336f027a Binary files /dev/null and b/docs/standards/CX-0081-BPDMCountryRisk/assets/OutputDataExample.png differ diff --git a/docs/standards/CX-0081-BPDMCountryRisk/assets/StandardisedDataExchange.png b/docs/standards/CX-0081-BPDMCountryRisk/assets/StandardisedDataExchange.png new file mode 100644 index 000000000..5f429345b Binary files /dev/null and b/docs/standards/CX-0081-BPDMCountryRisk/assets/StandardisedDataExchange.png differ diff --git a/docs/standards/CX-0081-BPDMCountryRisk/assets/access-mediums.jpeg b/docs/standards/CX-0081-BPDMCountryRisk/assets/access-mediums.jpeg new file mode 100644 index 000000000..183235177 Binary files /dev/null and b/docs/standards/CX-0081-BPDMCountryRisk/assets/access-mediums.jpeg differ diff --git a/docs/standards/CX-0084-FederatedQueriesInDataSpaces/CX-0084-FederatedQueriesInDataSpaces.md b/docs/standards/CX-0084-FederatedQueriesInDataSpaces/CX-0084-FederatedQueriesInDataSpaces.md new file mode 100644 index 000000000..255cbc6f9 --- /dev/null +++ b/docs/standards/CX-0084-FederatedQueriesInDataSpaces/CX-0084-FederatedQueriesInDataSpaces.md @@ -0,0 +1,1246 @@ +# CX-0084 Federated Queries in Data Spaces v1.2.0 + +## ABSTRACT + +This document provides a standard for a semantically-driven and state-of-the-art compute-to-data architecture for Catena-X, the so-called Knowledge Agents (KA) approach. It builds on well-established W3C-standards of the semantic web, such as OWL, SPARQL, SHACL, RDF etc. and makes these protocols usable to formulate powerful queries to the data space. Those queries can be used to answer business questions directly (comparable to a search engine) or they can be embedded in apps to include query results into workflows with more advanced visualization etc. The document addresses all stakeholders in Catena-X context that want to exchange data via the knowledge agents approach (data providers and consumers as well as app- and enablement service providers). + +## FOR WHOM IS THE STANDARD DESIGNED + +The standard is relevant for the following roles: + +- data & service provider/consumer +- business application provider + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +- External links have been changed to improve readability. +- The [examples](#16-examples) have been updated to reflect recent developments. In addition, the Asset Content Description subsection has been added. +- Code snippets and text updates in [Agent-Related EDC Assets](#agent-related-edc-assets) + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +The standard is relevant for the following roles: + +- Business Application Provider +- Enablement Service Provider +- Data Consumer +- Data Provider + +In the following, we call one of the following affected stakeholders/solutions Knowledge Agent (KA)-enabled if it passes the Conformity Assessment Criteria (CAC, see Section 1.2 and Chapter 2): + +- **Business Application Provider:** Applications that use KA technology on behalf of a Dataspace Participant (e.g. a Fleet Monitor, an Incident Reporting Solution). + +- **Enablement Service Provider:** Services to assist Dataspace Participants/Applications in processing data based on KA technology (e.g. a Graph Database, a Virtual Graph Binding Engine, an EDC Package). +As a second path, Companies are addressed that want to provide compute resources (for example by a server or other KA-enabled Applications or Services) based on instances/configurations of KA-enabled EDC Packages, for example a Recycling Software Specialist + +- **Data Consumer:** Companies that want to use data and logic (for example by KA-enabled Applications or Services) based on instances/configurations of KA-enabled EDC Packages, such as a Recycling Company or a Tier-2 Automotive Supplier +- **Data Provider:** Companies that want to provide data (for example by a backend database or other KA-enabled Applications or Services) based on instances/configurations of KA-enabled EDC Packages, for example an Automotive OEM. Companies that want to provide functions (for example by a REST endpoint or other KA-enabled Applications or Services) based on instances/configurations of KA-enabled EDC Packages, for example a Tier1 Sensor Device Supplier + +The CAC formulated in this standard comprise the following scope: + +- Query and Search (Basic Mechanism, Integration in User Experiences) +- Services for making use of various federated data sources being part of a data space (Data & Function Provisioning, Logic Development & Provisioning) +- Semantic Modelling +- Publishing, Negotiation, Transfer Protocols and Policy Enforcement via IDS (EDC) connector + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +The main objective concerning the approach described in this section is to create a state-of-the-art compute-to-data architecture for automotive use cases (and beyond) based on standards and best practices around GAIA-X and W3C. To reach this aim, full semantic integration, search and query with focus on relations between entities and data sovereignty is focused. In contrast to a simple file-based data transfer, this shifts the responsibility for the + +1. access, +2. authorization to the data and +3. processing of the data + +from the application development to the provider and hence ultimately, the actual owner of the data. + +![architecture.drawio.svg](./assets/architecture.drawio.svg) + +***Figure 1: Basic Overview about Knowledge Agents approach*** + +The most important concepts needed for the realization are summarized in Figure 1. The App in the figure serves the consumer by gathering, analyzing, and presenting the knowledge about business questions such as: How much of a certain material can be found in a specific vehicle series? It is assumed that the data which is needed to answer such questions is distributed over the network and cannot be found at one central place. + +To help collecting the data over the network, **Skills** are introduced. A Skill is a pre-formulated query (or: procedure) with limited scope such as: List all vehicle series that contain material produced in a certain location. The Skill is used to access all federated data instances via the tenant (= authentication and authorization scope) of the caller. + +A skill receives input in the form of a data set (we use a JSON notation in the following example): + +```csharp +[{"material":{"type":"literal","value":“Rubber”},"location":{"type":"literal","value":“Phuket”}}] +``` + +which drives the control flow, the filtering and aggregating of the information, and finally producing an output data set, for example: + +```csharp +[ + {"series":{"type":"uri","value":"OEM#4711"},"oem":{"type":"uri","value":"OEM"},"weightKg":{"type":"literal","datatype":"http://www.w3.org/2001/XMLSchema#float",”3.2”}}, + {"series":{"type":"uri","value":"EMO:0815"},"oem":{"type":"uri","value":"EMO"},"weightKg":{"type":"literal","datatype":"http://www.w3.org/2001/XMLSchema#float",”1.4”}} +] +``` + +In order to obtain the correct results in a federated system, all the participants of the skill execution need to have common understanding over the vocabulary (see following chapter). Relying on these conventions, an executor of a skill can calculate which providers are able to contribute or yield the necessary information in which sequence such that the resulting distributed operation will be performant. + +This coordinating job is taken over by the **Matchmaking Agent**, an endpoint that is mandatory for any KA-enabled Dataspace Participant. For that purpose, the Matchmaking Agent supports the SPARQL specification (see chapter 3) with the effect that the dataspace can be traversed as one large data structure. Hereby, the Consumer-Side Matchmaking Agent will – as driven by the built-in federation features of SPARQL - interact with the KA-enabled EDC in order to negotiate and perform the transfer of Sub-Skills which are partial expressions of the original SPARQL command to other Dataspace Participants. + +In turn, upon successful transfer of the Sub-Skill, the Provider-Side Matchmaking Agent(s) will be activated by their respective EDC. The precondition for this activation is of course that the Provider EDC first needs to offer a so-called Graph Asset: + +**Graph Assets** are a variant of ordinary Data Assets (see the ANNEX) in the Catena-X EDC Standard; while Data Assets typically refer to an actual backend system (e.g., an Blob in an Object Store, an AAS server, a REST endpoint), Graph Assets introduce another intermediary instance, the so-called Binding Agent. + +Simply put, the **Binding Agent** is a restricted version of the Matchmaking Agent (which speaks a profile, i.e., a subset of SPARQL specification, see the ANNEX) which is just focused on translating Sub-Skills of a particular business domain (Bill-Of-Material, Chemical Materials, Production Sites, etc.) into proper SQL- or REST based backend system calls. This scheme has several advantages: + +- For different types of backend systems, business domains and usage scenarios, different Binding Agent implementations (Caching Graph Store, SQL Binding Engine, REST Binding Engine) can be switched-in without affecting both the shared dataspace/semantic model and the mostly immutable backend systems/data models as well. +- Access to the backend systems can be optimized by JIT compilation technology. +- The same backend system/data model can be used in various Graph Assets/Use Cases and different roles and policies. +- Access to the backend system is decoupled by another layer of security, such that additional types of policies (role-based row-level and attribute-level access) can be implemented in the interplay of Matchmaking and Binding Agents. +- There is a clear distinction between advanced graph operations (including type inference and transitive/recursive traversal also via EDC) on the Matchmaking Level and efficient, but more restricted and secure graph operations on the Binding/Data Level. + +As mentioned earlier, essential for the realization of the idea is the creation, governance and discoverability of a well-defined semantic catalogue (the **Federated Catalogue**) which together with the data inside the Graph Assets forms a **Federated Knowledge Graph**. In this context, the definition of a Knowledge Graph (KG) as "a multi relational graph composed of entities and relations which are regarded as nodes and different types of edges, respectively" is extended with aspect of federation. We see a Federated KG as a KG where entities and relations reside physically distributed over multiple systems connected through a network and a common query language. We see semantic metadata as structural information to scope the entities and relations of the KG based on ontological principles. This is the agreement, necessary for the successful interplay of the distributed parties within the data space. + +To summarize, the Knowledge Agent standard shall achieve the following abilities: + +- the ability to define well-formed and composable computations/scripts (skills) which operate over various assets of various business partners. +- the ability to invoke and dynamically distribute these (sub-)skills over the relevant partners/connectors using an extensible agent interface. +- the ability to safely provide data and service assets via appropriate agent implementations which "bind" the skill to the backend execution engines (rather than mapping data). +- the ability for an agent/connector/business partner to decide + - whether to hide particular data and computations inside a sub-skill + - whether to delegate/federate particular computations/sub-skills to other agents + - whether to migrate or clone an agent/asset from a partner +- the ability to describe data and service assets as well as appropriate federation policies in the IDS vocabulary in order to allow for a dynamic matchmaking of skills and agents. +- the ability to define domain/use case-based ontologies which form the vocabulary used in the skill definitions. +- the ability to visualize and develop the ontologies and skills in appropriate SDKs and User Experience components. + +### 1.3 ARCHITECTURE OVERVIEW + +> *This section is non-normative* + +This chapter gives an overview how the concept elaborated in previous chapter should be implemented. In this context generic building blocks were defined (see Figure 3) which can be implemented with different open source or COTS solutions. In the scope of Catena-X project these building blocks are instantiated with a reference implementation based on open source components. The detailed architecture that follows this reference implementation can be found as a [high-level architecture](https://eclipse-tractusx.github.io/docs-kits/next/kits/knowledge-agents/development-view/architecture) in the Knowledge Agent KIT. + +![layer_architecture.drawio.svg](./assets/layer_architecture.drawio.svg) + +***Figure 2: KA building blocks (Solid-Lines Denote Standard-Affected Layers & Components)*** + +In the following paragraphs, all building blocks relevant for this version of the standard are introduced: + +#### Ontology models + +Ontologies, as defined by W3C Web Ontology Language [OWL 2](https://www.w3.org/OWL/) standard, provide the core of the KA catalogue. OWL comes with several interpretation [profiles](https://www.w3.org/TR/owl2-profiles/) for different types of applications. For model checking and data validation (not part of this standard), the Rule Logic (RL) profile is used. For query answering/data processing (part of this standard), the Existential Logic (EL) profile (on the Dataspace Layer) and the Query Logic (QL) profile (on the Binding Layer) is used. Furthermore, RDF Terse Triple Language [TTL](https://www.w3.org/TR/turtle/) format is used to divide/merge large ontologies into/from modular domain ontology files. + +The actual guidelines for how these domain ontologies are designed such that they are consistent with other is described in the sibling standard CX - 0067 Ontology Models to realize federated query in Catena-X. + +Semantic Models are hosted in the Ontology Hub that is a central service to the dataspace based on [git over http](https://www.git-scm.com/docs/http-protocol). + +#### Data Consumption Layer/Query Definition + +This layer comprises all applications which utilize provided data and functions of business partners to achieve a direct business impact and frameworks which simplify the development of these applications. Thus, this layer focuses on using a released Semantic Model (or a use-case/role-specific excerpt thereof) as a vocabulary to build flexible queries (Skills) and integrating these Skills in data consuming apps. Skills can be easily integrated in these apps as stored procedure. Hence, skill and app development can be decoupled to increase efficiency of the app development process. + +[SPARQL 1.1](https://www.w3.org/TR/sparql11-query/) specification is used as a language and protocol to search for and process data across different business partners. As a part of this specification, the [QUERY RESULTS JSON](https://www.w3.org/TR/sparql11-results-json/) and the [QUERY RESULTS XML](https://www.w3.org/TR/rdf-sparql-XMLres/) formats are used to represent both the answer sets generated by SPARQL skills and the sets of input parameters that a SPARQL skill should be applied to. For answer sets, additional formats such as the [QUERY RESULTS CSV and TSV](https://www.w3.org/TR/sparql11-results-csv-tsv/) format may be supported. Required is the ability to store and invoke SPARQL queries as parameterized procedures in the dataspace; this is a KA-specific adaption to the SPARQL endpoint (the so-called KA-MATCH profile, see ANNEX) that is also captured in the concise [OpenAPI specification](https://eclipse-tractusx.github.io/docs-kits/next/kits/knowledge-agents/development-view/api). This API allows for an extended response behaviour which introduces a warning status (matching the HTTP response status code “203 - Non-Authoritative Information”) and an additional response header “cx_warning” that lists abnormal events or trace information that appeared during the processing in a data-sovereign manner. + +#### Dataspace Layer + +The base technology for building data spaces is the Eclipse Dataspace Connector (EDC) which should be extended to operate as a HTTP/S contracting & transfer facility for the SPARQL-speaking Matchmaking Agent. To resolve dataspace offers and addresses using the ontological vocabulary, the Matchmaking Agent keeps a default meta-graph, the Federated Catalogue, that is used to host the Semantic Model and that is regularly synchronized with the relevant dataspace information including the offers of surrounding business partners/EDCs. + +The EDC interacts with the so-called Matchmaking Agent which is the first stage of SPARQL processing. It operates as the main invocation point to the Data Consuming Layer (using the KA-MATCH SPARQL profile). Furthermore, It operates as the main bridging point between incoming EDC transfers (from an “Agent Source” in the KA-TRANSFER SPARQL profile) and the underlying Binding Layer (speaking the KA-BIND SPARQL profile). And it implements federation by delegating any outgoing SERVICE/GRAPH contexts back to the EDC (using the KA-TRANSFER profile). + +![dataspace_layer.drawio.svg](./assets/dataspace_layer.drawio.svg) + +***Figure 3: Standard-Affected Dataspace Components*** + +Since EDC and Matchmaking Agent are bidirectionally coupled, implementations could merge Data Plane and Matchmaking Agent into a single package, the so-called Agent Plane. Agent Planes and ordinary Data Planes can co-exist due to our design choices. + +The so called Federated Catalogue is an RDF data storage facility for the Matchmaking Agent. It could be an in-memory triple store (that is restored via downloading TTL and refreshing dataspace catalogues upon restart), a dedicated graph database using btree index files or even an ordinary relational database that has been adapted to fit to the chosen Matchmaking Agent implementation. One example of such an interface is the Eclipse [RDF4J SAIL](https://rdf4j.org/documentation/reference/sail/) that is common for many SPARQL and RDF persistence engines. + +The Federated Catalogue should initially download the complete Semantic Model that has been released for the target environment from the [Ontology Hub](http://w3id.org/catenax). It should also contain a list of business partners and their roles which form the surrounding dataspace neighborhood of the tenant. For that purpose, it could use BPDM and Self-Description Hub services in order to lookup EDC addresses and additional domain information (sites, geo addresses). It should then be frequently updated with “live” information by invoking the EDC data management API to regularly obtain catalogue information. +The portion of the Semantic Model describing these meta-data (Business Partners, Sites, Addresses, Use Cases, Use Case Roles, Connectors & Assets) is called the [Common domain ontology](https://w3id.org/catenax/ontology/common) and is mandatory for all releases/excerpts of the Semantic Model. + +All relevant profiles and asset descriptions are explained in detail in the ANNEX. The interplay of the components and their respective interfaces in Figure 3 forms the basis of interoperability between EDC and backend systems within a single business partner's environment as well as interoperability between multiple business partners' dataspace segments. + +Therefore, the Conformity Assessment (CA) as well as the individual Conformity Assessment Criteria (CAC) envisaged in this standard (see #2-conformity-assessment-criteria) have a focus on verifying the capabilities and functionalities of exactly these interfaces: + +- between Consuming Application and Matchmaking Agent (KA-MATCH protocol profile - see #22-cac-for-matchmaking-agent) +- between Matchmaking Agent and Binding Agents (KA-BIND protocol profile - see #24-cac-for-binding-agents and #22-cac-for-matchmaking-agent) +- between EDC and Matchmaking Agent (Management API, Negotiation API, Endpoint Callback, KA-TRANSFER Invocation and Delegation - see #21-cac-for-edc and #22-cac-for-matchmaking-agent) +- between Federated Catalogue and EDC (Management/Catalogue API - see #21-cac-for-edc and #23-cac-for-federated-catalogue) +- between Matchmaking Agent and Federated Catalogue (Storage API - see #23-cac-for-federated-catalogue and #22-cac-for-matchmaking-agent) +- between Federated Catalogue and Core Services (raw download from git branch/tag - see #23-cac-for-federated-catalogue and #25-cac-for-ontology-hub) + +#### Backend Systems + +Legacy IT landscape of data space participants consisting of various backend systems, such as PLM, ERP, ObjectStores mostly located in the Enterprise Intranet and hosted/goverened by the business departments. Here, the actual data sources of all Catena-X participants is originated where they are served using custom, but mission-critical business or technological APIs in specific, transaction-oriented formats. From the standpoint of Knowledge Agents, also Digital Twin servers and registries such as following the [IDTA AAS standards](https://industrialdigitaltwin.org/) can be regarded as backend systems. + +#### Virtualization Layer + +The data virtualization layer fulfills the function of making the company internal, department-hosted data available for cross-company data exchange scenarios, e.g. via data lakes, data warehouses or other enterprise middleware. Instead of connecting each and every backend system separatly to an external data source/sink (such as Catena-X) it often makes sense to have this additional layer on top of backend systems which orchestrates data demand and supply across the systems. Depending on company IT architecture different technologies, such as virtual SQL databases, API gateways and extraction & transformation pipelines, can be used to build up this layer. + +A special case of a virtualisation is the AAS-KA Bridge which makes the AAS API accessible to the upcoming binding layer in a generic manner. This will be elaborated in a later version of this standard. + +#### Binding Layer + +Finally, the missing link between the Dataspace Layer and the Virtualization Layer is the Binding Layer. Hereby rather than mapping the data between different formats (e.g. Data Tables in CSV Format to and from Data Graphs in the TTL format) which is a mostly resource-consuming data transformation process, binding rather rewrites the actual queries (e.g. SPARQL into SQL, SPARQL into GraphQL or REST). In order to make this query rewriting not too complicated, a restricted subset of SPARQL is envisaged. + +A special case of a binding is the KA-AAS Bridge which maps between SPARQL modules in the same layer and AAS (as the target API). This will be elaborated in a later version of this standard. + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is non-normative* + +Certification against this standard is particulary relevant for Enablement Service Providers that provide solutions based on Knowledge Agents technology. All other data space participants (see audience & scope: data providers, data consumers, app providers) do not require certification but may use this standard as additional source of information if they want to use KA technology. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). +Please refer to the association homepage for the process of conformity assessment and certification. + +The Conformity Assessment Criteria (and proposed Conformity Assessment Methods) will be listed in Chapter 2 for the respective building blocks +that are relevant for KA Enablement. + +Corresponding to this standard, a [testbed blueprint](https://eclipse-tractusx.github.io/docs-kits/kits/knowledge-agents/operation-view/testbed) is provided in the Knowledge Agent KIT that covers most of the following CACs and CAMs. Up till now there is no operated testbed available. Thus, until this situation is resolved CAB may accept a self-assessment that all CACs are fulfilled by respective Enablement Service Provider. + +### 1.6 Examples + +The following examples are based on the Behaviour Twin use case (CX-0059 Use Case Behaviour Twin Endurance Predictor v1.3.0). + +#### Data Binding + +The following is an example binding in the [OBDA](https://ontop-vkg.org/tutorial/basic/university-1.html#mappings) format which translates between RDF triples (over the Catena-X domain ontologies related to vehicles and reliablity) and an underlying relational SQL database. + +``` +[PrefixDeclaration] +cx-common: https://w3id.org/catenax/ontology/common# +cx-core: https://w3id.org/catenax/ontology/core# +cx-vehicle: https://w3id.org/catenax/ontology/vehicle# +cx-reliability: https://w3id.org/catenax/ontology/reliability# +cx-taxo: https://w3id.org/catenax/taxonomy# +uuid: urn:uuid: +bpnl: bpn:legal: +owl: http://www.w3.org/2002/07/owl# +rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns# +xml: http://www.w3.org/XML/1998/namespace +xsd: http://www.w3.org/2001/XMLSchema# +json: https://json-schema.org/draft/2020-12/schema# +obda: https://w3id.org/obda/vocabulary# +rdfs: http://www.w3.org/2000/01/rdf-schema# + +[MappingDeclaration] @collection [[ +mappingId vehicles +target uuid:{catenaXId} rdf:type cx-vehicle:Vehicle ; cx-vehicle:vehicleIdentificationNumber {localIdentifiers_van}^^xsd:string; cx-vehicle:manufacturer bpnl:{localIdentifiers_manufacturerId}; cx-vehicle:productionDate {manufacturingInformation_date}^^xsd:date. +source SELECT "catenaXId", "localIdentifiers_van", "localIdentifiers_manufacturerId", "manufacturingInformation_date" FROM "HI_TEST_OEM"."CX_RUL_SerialPartTypization_Vehicle" vehicles + +mappingId partsvehicle +target uuid:{childCatenaXId} cx-vehicle:isPartOf uuid:{catenaXId} . +source SELECT "catenaXId", "childCatenaXId" FROM "HI_TEST_OEM"."CX_RUL_AssemblyPartRelationship" vehicleparts + +mappingId loadspectrum +target uuid:{catenaXId}/{targetComponentId}/{metadata_componentDescription} rdf:type cx-reliability:LoadSpectrum; cx-core:id cx-taxo:{metadata_componentDescription}; cx-core:name {metadata_projectDescription}^^xsd:string; cx-reliability:description {metadata_routeDescription}^^xsd:string; cx-reliability:countingValue {header_countingValue}^^xsd:string; cx-reliability:countingUnit {header_countingUnit}^^xsd:string; cx-reliability:countingMethod {header_countingMethod}^^xsd:string; cx-reliability:channels {header_channels}^^json:Object; cx-reliability:classes {body_classes}^^json:Object; cx-reliability:values {body_counts_countsList}^^json:Object . +source SELECT "catenaXId", "targetComponentId", "metadata_projectDescription", "metadata_componentDescription", "metadata_routeDescription", "metadata_status_date", "header_countingValue", "header_countingUnit", "header_countingMethod", "header_channels", "body_counts_countsList", "body_classes" FROM "HI_TEST_OEM"."CX_RUL_LoadCollective" loadspectrum + +... + +]] +``` + +#### Function Binding + +The following is an example binding in the [RDF4J Repository Configuration Language](https://rdf4j.org/documentation/tools/repository-configuration/) which translates between RDF triples (over the Catena-X domain ontologies related to reliability and behavioural simulations) and an underlying relational REST backend performing a lifetime prognosis. + +``` +# +# Rdf4j configuration for a rul-specific remoting +# +@prefix rdf: . +@prefix rdfs: . +@prefix rep: . +@prefix sr: . +@prefix sail: . +@prefix sp: . +@prefix xsd: . +@prefix json: . +@prefix dct: . +@prefix cx-fx: . +@prefix cx-common: . +@prefix cx-core: . +@prefix cx-vehicle: . +@prefix cx-reliability: . +@prefix cx-behaviour: . + +[] rdf:type rep:Repository ; + rep:repositoryID "rul" ; + rdfs:label "Remainig Useful Life Functions Repository" ; + rep:repositoryImpl [ + rep:repositoryType "openrdf:SailRepository" ; + sr:sailImpl [ + sail:sailType "org.eclipse.tractusx.agents:Remoting" ; + cx-fx:supportsInvocation cx-behaviour:RemainingUsefulLife; + cx-fx:callbackAddress ; + ] + ]. + +cx-behaviour:RemainingUsefulLife rdf:type cx-fx:Function; + dct:description "Remaining Useful Life is an asynchronous batch invocation."@en ; + dct:title "Remaining Useful Life" ; + cx-fx:targetUri "http://service-backend:5005/api/rul2"; + cx-fx:invocationMethod "POST-JSON"; + cx-fx:invocationMethod "POST-JSON"; + cx-fx:invocationIdProperty "header.notificationID,content.requestRefId"; + cx-fx:callbackProperty "header.respondAssetId". + +cx-behaviour:countingUnit rdf:type cx-fx:Input; + dct:description "Counting Unit of Load Spectrum."@en ; + dct:title "Loadspectrum Counting Unit"; + cx-fx:dataType xsd:string; + cx-fx:argumentName "content.endurancePredictorInputs.0.classifiedLoadSpectrum{https://w3id.org/catenax/ontology/behaviour#observationType}.header.countingUnit". + +cx-behaviour:countingValue rdf:type cx-fx:Input; + dct:description "Counting Value Name of Load Spectrum."@en ; + dct:title "Loadspectrum Counting Value"; + cx-fx:dataType xsd:string; + cx-fx:argumentName "content.endurancePredictorInputs.0.classifiedLoadSpectrum{https://w3id.org/catenax/ontology/behaviour#observationType}.header.countingValue,content.endurancePredictorInputs.0.classifiedLoadSpectrum{https://w3id.org/catenax/ontology/behaviour#observationType}.body.counts.countsName". + +cx-behaviour:countingMethod rdf:type cx-fx:Input; + dct:description "Counting Method of Load Spectrum."@en ; + dct:title "Loadspectrum Counting Method"; + cx-fx:dataType xsd:string; + cx-fx:argumentName "content.endurancePredictorInputs.0.classifiedLoadSpectrum{https://w3id.org/catenax/ontology/behaviour#observationType}.header.countingMethod". + +cx-behaviour:headerChannels rdf:type cx-fx:Input; + dct:description "Channels of Load Spectrum."@en ; + dct:title "Loadspectrum Channels"; + cx-fx:dataType json:Object; + cx-fx:argumentName "content.endurancePredictorInputs.0.classifiedLoadSpectrum{https://w3id.org/catenax/ontology/behaviour#observationType}.header.channels". + +cx-behaviour:bodyClasses rdf:type cx-fx:Input; + dct:description "Classes of Load Spectrum."@en ; + dct:title "Loadspectrum Classes"; + cx-fx:dataType json:Object; + cx-fx:argumentName "content.endurancePredictorInputs.0.classifiedLoadSpectrum{https://w3id.org/catenax/ontology/behaviour#observationType}.body.classes". + +cx-behaviour:bodyCountsList rdf:type cx-fx:Input; + dct:description "Counts List of Load Spectrum."@en ; + dct:title "Loadspectrum Counts List"; + cx-fx:dataType json:Object; + cx-fx:argumentName "content.endurancePredictorInputs.0.classifiedLoadSpectrum{https://w3id.org/catenax/ontology/behaviour#observationType}.body.counts.countsList". + + ... + +cx-behaviour:RemainingUsefulLifeResult rdf:type cx-fx:Result; + dct:description "The asynchronous notification response."@en ; + dct:title "Asynchronous notification response." ; + cx-fx:callbackProperty "header.referencedNotificationID"; + cx-fx:outputProperty "content.endurancePredictorOutputs"; + cx-fx:output cx-behaviour:remainingOperatingHours; + cx-fx:output cx-behaviour:remainingRunningDistance. + +cx-behaviour:remainingOperatingHours rdf:type cx-fx:ReturnValue; + dct:description "Predicted Operating Hours of Remaining Useful Life Response"@en ; + dct:title "Remaining Useful Life Operating Hours" ; + cx-fx:valuePath "0.remainingUsefulLife.remainingOperatingHours"; + cx-fx:dataType xsd:float. + +cx-behaviour:remainingRunningDistance rdf:type cx-fx:ReturnValue; + dct:description "Predicted Distance of Remaining Useful Life Response"@en ; + dct:title "Remaining Useful Life Distance" ; + cx-fx:valuePath "0.remainingUsefulLife.remainingRunningDistance"; + cx-fx:dataType xsd:int. +``` + +#### Asset content description + +The Asset Content Description explicitly states what data the asset provides. [SHACL](https://www.w3.org/TR/shacl/) (Shape Constraint Language) is used to describe the content. As shown in the following examples, both data and functions can be described. At the same time, input parameters for functions can be described using the **cx-sh:hasAsArgument** property to specify what data is required as input (see [federated query](#federated-query)). This description allows automatic detection of data and its assets in a query. The descriptions are linked to assets using **sh:shapesGraph** property (see [Agent-Related EDC Assets](#agent-related-edc-assets)) + +Asset content description of load spectrum data: + +``` +@prefix rdf: . +@prefix rdfs: . +@prefix schema: . +@prefix sh: . +@prefix xsd: . +@prefix edc: . +@prefix cx-common: . +@prefix cx-core: . +@prefix cx-vehicle: . +@prefix cx-fx: . +@prefix cx-behaviour: . +@prefix cx-reliability: . +@prefix cx-sh: . +@prefix cx-taxo: . +@prefix : . + +:LoadSpectrumShape a sh:NodeShape ; + sh:targetClass cx-reliability:LoadSpectrum; + sh:property :observationOfShape, + :countingValueShape, + :countingUnitShape, + :countingMethodShape, + :channelsShape, + :classesShape, + :valuesShape. + +:observationOfShape a sh:PropertyShape; + sh:path cx-reliability:observationOf; + sh:in (cx-taxo:GearOil cx-taxo:GearSet cx-taxo:Clutch). + +:countingValueShape a sh:PropertyShape; + sh:path cx-reliability:countingValue. + +:countingUnitShape a sh:PropertyShape; + sh:path cx-reliability:countingUnit. + +:countingMethodShape a sh:PropertyShape; + sh:path cx-reliability:countingMethod. + +:countingMethodShape a sh:PropertyShape; + sh:path cx-reliability:countingMethod. + +:channelsShape a sh:PropertyShape; + sh:path cx-reliability:channels. + +:classesShape a sh:PropertyShape; + sh:path cx-reliability:classes. + +:valuesShape a sh:PropertyShape; + sh:path cx-reliability:values. + +``` + +Asset content description of prognosis (remaining useful life) function: + +``` +@prefix rdf: . +@prefix rdfs: . +@prefix schema: . +@prefix sh: . +@prefix xsd: . +@prefix edc: . +@prefix cx-common: . +@prefix cx-core: . +@prefix cx-vehicle: . +@prefix cx-fx: . +@prefix cx-behaviour: . +@prefix cx-reliability: . +@prefix cx-sh: . +@prefix cx-taxo: . + +# Prognosis Function +:PrognosisFunctionShape rdf:type sh:NodeShape ; + sh:targetClass cx-behaviour:PrognosisFunction; + sh:property [ + cx-sh:hasAsArgument cx-reliability:countingMethod; + sh:path cx-behaviour:countingMethod; + ]; + sh:property [ + cx-sh:hasAsArgument cx-reliability:countingValue; + sh:path cx-behaviour:countingValue; + ]; + sh:property [ + cx-sh:hasAsArgument cx-reliability:countingUnit; + sh:path cx-behaviour:countingUnit; + ]; + sh:property [ + cx-sh:hasAsArgument cx-reliability:channels; + sh:path cx-behaviour:headerChannels; + ]; + sh:property [ + cx-sh:hasAsArgument cx-reliability:classes; + sh:path cx-behaviour:bodyClasses; + ]. + +:RemainingUsefulLifeShape rdf:type sh:NodeShape ; + cx-sh:extensionOf :PrognosisFunctionShape; + sh:targetClass cx-behaviour:RemainingUsefulLife ; + sh:property[ + cx-sh:hasAsArgument cx-reliability:observationOf; + sh:path cx-behaviour:observationType; + sh:in ( cx-taxo:GearSet cx-taxo:GearOil ); + ]; + sh:property :RemainingUsefulLifeResultShape. + +:RemainingUsefulLifeResult rdf:type sh:PropertyShape; + cx-sh:outputOf :RemainingUsefulLifeShape; + sh:path cx-behaviour:RemainingUsefulLifeResult . +``` + +#### Federated Query + +The following is an example of a parameterised query in SPARQL (using the Catena-X reliability and behaviour domains) that, given a vehicle identification number (@van), performs a lifetime prognosis for its differential gear over two dataspace hops (respective OEM and SUPPLIER) based on previous asset content descriptions. + +``` +PREFIX sh: http://www.w3.org/ns/shacl# +PREFIX schema: http://schema.org/ +PREFIX rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns# +PREFIX rdfs: http://www.w3.org/2000/01/rdf-schema# +PREFIX xsd: http://www.w3.org/2001/XMLSchema# +PREFIX json: https://json-schema.org/draft/2020-12/schema# +PREFIX cx-sh: https://w3id.org/catenax/ontology/schema# +PREFIX cx-common: https://w3id.org/catenax/ontology/common# +PREFIX cx-core: https://w3id.org/catenax/ontology/core# +PREFIX cx-reliability: https://w3id.org/catenax/ontology/reliability# +PREFIX cx-schema: https://w3id.org/catenax/ontology/schema# +PREFIX cx-vehicle: https://w3id.org/catenax/ontology/vehicle# +PREFIX cx-behaviour: https://w3id.org/catenax/ontology/behaviour# +PREFIX cx-taxo: https://w3id.org/catenax/taxonomy# + +################################################################ +# Sample for a Provider-Deployed Goal-Oriented SparQL Skill which +# - Depending on the targetted result +# - Finds the right supplier prognosis asset and its preconditions +# - jumps into the OEM-owned reliability asset to obtain the required data +# - feeds the gathered data back into the respective supplier connector/agent +# to perform a behavioural prognosis +# Author: cgjung +# (c) 2023-2024 Catena-X assocation +################################################################ + +SELECT DISTINCT ?van ?supplier ?vehicle ?assembly ?operatingTime ?mileage ?prognosis WHERE { + + VALUES (?van ?aggregate ?result_type) { + ("@van"^^xsd:string "Differential Gear"^^xsd:string \<@resultType\>) + } + + # Determine the prognosis assets + ?output sh:path ?result_type. + ?output cx-sh:outputOf ?functionShape. + ?assetFunction cx-sh:shapeObject ?functionShape. + ?functionConnector cx-common:offers ?assetFunction. + ?functionShape cx-sh:extensionOf* ?parentFunctionShape. + ?functionShape sh:targetClass ?function. + ?parentFunctionShape sh:property ?functionProperty. + ?functionProperty cx-sh:hasAsArgument ?argument. + ?functionProperty sh:in ?parameters. + ?parameters rdf:rest*/rdf:first ?ls_type. + + # Determine the target + ?assetData cx-sh:shapeObject ?nodeShape. + ?dataConnector cx-common:offers ?assetData. + ?nodeShape sh:property ?propertyShape. + ?propertyShape sh:path ?argument. + ?propertyShape sh:in ?parameters_target. + ?parameters_target rdf:rest*/rdf:first ?ls_type. + + SERVICE ?dataConnector { + GRAPH ?assetData { + ?vehicle rdf:type cx-vehicle:Vehicle; + cx-vehicle:vehicleIdentificationNumber ?van. + + ?assembly rdf:type cx-vehicle:Part; + cx-vehicle:name ?aggregate; + cx-vehicle:isPartOf ?vehicle; + cx-vehicle:supplier ?supplier. + + ?teleAnalysis rdf:type cx-reliability:Analysis; + cx-reliability:analysedObject ?assembly; + cx-reliability:operatingHoursOfVehicle ?operatingTime; + cx-reliability:mileageOfVehicle ?mileage; + cx-core:startDateTime ?recordDate; + cx-reliability:result [ + cx-core:id ?ls_type; + cx-core:name ?ls_name; + cx-reliability:countingValue ?ls_value; + cx-reliability:countingUnit ?ls_unit; + cx-reliability:countingMethod ?ls_method; + cx-reliability:channels ?ls_channels; + cx-reliability:classes ?ls_classes; + cx-reliability:values ?ls_values + ]. + } + } + + SERVICE ?functionConnector { + GRAPH ?assetFunction { + SELECT ?prognosis WHERE { + ?invocation a ?function; + cx-behaviour:sender ; + cx-behaviour:senderConnector ; + cx-behaviour:recipient ; + cx-behaviour:recipientConnector ; + cx-behaviour:targetDate ?recordDate; + cx-behaviour:timeStamp ?recordDate; + cx-behaviour:component ?assembly; + cx-behaviour:observationType ?ls_type; + cx-behaviour:statusDate ?recordDate; + cx-behaviour:statusOperatingHours ?operatingTime; + cx-behaviour:statusMileage ?mileage; + cx-behaviour:countingValue ?ls_value; + cx-behaviour:countingUnit ?ls_unit; + cx-behaviour:countingMethod ?ls_method; + cx-behaviour:headerChannels ?ls_channels; + cx-behaviour:bodyClasses ?ls_classes; + cx-behaviour:bodyCountsList ?ls_values; + ?result_type ?prognosis. + } + } + } # SUPPLIER#CATALOG + +} # SELECT +``` + +## 2. Conformity Assessment Criteria + +> *This section is normative* + +### 2.1 CAC for EDC + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    CACComponentNormative StatementProposed Method
    2.1.1EDC Control PlaneMUST conform to the CX EDC Standard
    		See CX-0018
    2.1.2EDC Control PlaneMUST support the “HttpProxy” transfer process type which instruments/switches between different data planes according to the asset "type".Configuration Review
    EDC property
    edc.dataplane.selector.*
    destinationtypes
    should contain
    HttpProxy

    Data Consumers: CAB offers a TESTGRAPHASSET and a TESTSKILLASSET.
    Assessed Party successfully negotiates and initiates a "HttpProxy" transfer for each of those assets.
    Data Providers: Assessed Party offers a TESTGRAPHASSET.
    CAB successfully negotiates and initiates a "HttpProxy" transfer.
    Skill Providers: Assessed Party offers a TESTSKILLASSET.
    CAB successfully negotiates and initiates a "HttpProxy" transfer.
    2.1.3EDC Control PlaneMUST register at least one KA-Enabled Data PlaneConfiguration Review
    Data Consumers: EDC property
    dc.dataplane.selector.*
    sourcetypes
    should contain "HttpData".
    Data Providers: EDC property
    dc.dataplane.selector.*
    sourcetypes
    should contain "cx-common:Protocol?w3c:http:SPARQL".
    Skill Providers: EDC property
    dc.dataplane.selector.*
    sourcetypes
    should contain "cx-common:Protocol?w3c:http:SKILL".
    2.1.4EDC Control PlaneSHOULD support dynamic endpoint callback listeners.
    OR MUST register at least one Matchmaking Agent
    callback endpoint as listener    		Code/Configuration Review
    EDC extension org.eclipse.edc:transfer-pull-http-dynamic-receiver is installed
    OR edc.receiver.http
    EDC property points to the Matchmaking Agent callback endpoint
    2.1.5EDC Control PlaneMAY support an extended validation endpoint for extended
    graph policies which need access to a runtime context    		Assessed Party demonstrates an endpoint which accepts a
    valid transfer token together
    with a JSON object representing the runtime context.
    2.1.6EDC Data PlaneMUST conform to the CX EDC Standard,
    specifically MUST implement the “HttpProxy” transfer process type
    in combination with the “HttpData” asset type    		See CX-0018
    2.1.7EDC Data PlaneMUST support the “HttpProxy” transfer process type in
    combination with the "cx-common:Protocol?w3c:http:SPARQL"
    and cx-common:Protocol?w3c:http:SKILL asset types.
    The registered Source implementation MUST support Graph Asset specifications and support the KA-TRANSFER protocol listed in the ANNEX.
    In particular it must process the “cx_header” parameter
    MUST support the “header:Accepts” and “header:Host” asset address properties.
    MUST require the “proxyBody”, “proxyQueryParams” and
    “proxyMethod” asset address properties to be true.
    MUST require the “proxyPath” asset address properties to be false.
    MUST rewrite the query (as parameter or body)
    to replace all occurrences of the asset:prop:id property
    by the “baseUrl” property
    MAY rewrite the query driven by additional asset address properties (“sh:shapeGraph”)
    MAY validate the query using an extended validation
    endpoint in the Control Plane and by deriving
    additional runtime context from parsing the query and the payload
    MUST delegate to the Matchmaking Agent using the KA-MATCH profile    		Code/Configuration Review
    Data Provider: Assessed Party offers a TESTGRAPHASSET.
    CAB performs the transfer and evaluates the result.
    Skill Provider: Assessed Party offers a TESTSKILLASSET.
    CAB performs transfers in remote and local mode and evaluates the results.
    Data Consumer: CAB offers a TESTGRAPHASSET and a TESTSKILLASSET.
    Assessed Party performs transfers to each of them (both remote and local mode for TESTSKILLASSET) and evaluates the results.
    + +### 2.2 CAC for Matchmaking Agent + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    CACComponentNormative StatementProposed Method
    2.2.1Matchmaking AgentMUST support an endpoint callback conforming to the CX EDC StandardSee CX-0018
    Assessed Party demonstrates a self-call with a TESTENDPOINTDATAREFERENCE tailored to a CAB-given endpoint.
    A subsequent self-call with a TESTENDPOINTSPARQL should hit the given CAB target.
    2.2.2Matchmaking AgentMUST execute “Service <url>” contexts where the
    url starts with the “edc” or “edcs” schema,
    by parsing the sub-context or the url
    for an assetName (url#assetName or “GRAPH <assetName>”)
    and subsequently engage into a "HttpProxy"
    negotiation/transfer process with the Control plane addressed
    by the url when replacing the “edc” scheme
    with “http” and the “edcs” scheme with “https” respectively
    MAY perform simultaneous negotiations/transfers due to “Service ?url” calls when "?url"
    is bound to multiple addresses.    		CAB offers TESTGRAPHASSET
    Assessed Party performs a TESTSERVICESPARQL to demonstrate successful delegation
    2.2.3Matchmaking AgentMUST support the “/agent” GET endpoint
    of the KA-MATCH SPARQL profile    		CAB offers TESTSKILLASSET
    Assessed Party performs a parameterized TESTGETSKILL request to successfully demonstrate invocation variants and error behaviour
    2.2.4Matchmaking AgentMUST implement the “/agent” POST endpoint of the
    KA-MATCH SPARQL profile    		CAB offers TESTSKILLASSET
    Assessed Party performs a parameterized TESTPOSTSKILL request to successfully demonstrate invocation variants and error behaviour
    2.2.5Matchmaking AgentMUST implement the “/agent/skill” POST endpoint
    of the KA-MATCH SPARQL profile    		Assessed Party invokes the endpoint using a TESTSKILL
    to successfully register a skill.
    Assessed Party then performs a parameterized TESTGETREGISTEREDSKILL request to successfully demonstrate invocation.
    2.2.6Matchmaking AgentMAY perform a realm-mapping from the tenant domain
    (Authentication Scheme, such as API-Key and Oauth2)
    into the dataspace domain (EDC tokens)    		Assessed Party demonstrates three TESTAUTHENTICATION calls, a successful one with a valid authentication code/token and two failing calls one with an invalid and one with a lacking code/token
    2.2.7Matchmaking AgentSHOULD operate on the Federated Catalogue as an RDF store.Assessed Party adds CAB control plane to its list of synchronized connectors.
    CAB changes its catalogue.
    Assessed Party demonstrates the DATASPACE skill reflecting that change
    2.2.8Matchmaking AgentSHOULD be able to process Ontology models along the CX Ontology Standard and OWL-EL profileSee CX-0067
    Assessed Party performs a TESTONTOLOGIYEL query.
    + +### 2.3 CAC for Federated Catalogue + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    CACComponentNormative StatementProposed Method
    2.3.1Federated CatalogMUST contain the Catena-X Ontology
    relevant to the respective release.    		CAB accesses the Catena-X Ontology in the Ontology Hub.
    Assessed Party performs a TESTONTOLOGY retrieval to validate they are equivalent.
    2.3.2Federated CatalogMUST contain data instantiating the Catena-X Common Domain Ontology (cx-common)
    related to the business partners of the assessed tenant    		Assessed Party adds CAB control plane to its list of synchronized connectors.
    Assessed Party performs a TESTCATALOGUE retrieval to validate the available instance data against the BPNLs including the CAB
    2.3.3Federated CatalogMUST frequently update catalogue data instantiating
    the Common Domain Ontology of the Semantic Model    		Assessed Party adds CAB control plane to its list of synchronized connectors.
    Assessed Party performs a TESTCABASSETS retrieval to demonstrate that both catalogues are synchronized.
    + +### 2.4 CAC for Binding Agents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    CACComponentNormative StatementProposed Method
    2.4.1Data Binding Agent (Only relevant for Enablement Service Provider)MUST implement the POST endpoint of the KA-BIND SPARQL profileAssessed Party performs a TESTBINDINGSPARQLPOST call to demonstrate profile support
    2.4.2Data Binding Agent (Only relevant for Enablement Service Provider)MAY implement the GET endpoint of the KA-BIND SPARQL profileAssessed Party performs a TESTBINDINGSPARQLGET call to demonstrate profile support
    2.4.5Data Binding Agent (Only relevant for Enablement Service Provider)SHOULD be able to process Ontology models along the CX Ontology Standard and OWL-QL profileSee CX-0067
    Assessed Party performs a TESTONTOLOTYQLDATA query.
    2.4.3Function Binding Agent (Only relevant for Enablement Service Provider)MUST implement the POST endpoint of the KA-BIND-F profileAssessed Party performs a TESTFUNCTIONBINDINGSPARQLPOST call to demonstrate profile support
    2.4.4Function Binding Agent (Only relevant for Enablement Service Provider)MAY implement the GET endpoint of the KA-BIND-F profileAssessed Party performs a TESTFUNCTIONBINDINGSPARQLGET call to demonstrate profile support
    2.4.6Function Binding Agent (Only relevant for Enablement Service Provider)SHOULD be able to process Ontology models along the CX Ontology Standard and OWL-QL profileSee CX-0067
    Assessed Party performs a TESTONTOLOGYQLFUNCTION query.
    + +### 2.5 CAC for Ontology Hub + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    CACComponentNormative StatementProposed Method
    2.5.1Ontology Hub (only for Core Service Provider)MUST implement the git/http protocolAssessed Party authorizes the CAB for acccess.
    CAB uses a git client to perform the most common git operations (clone, checkout, commit/push, fetch).
    CAB verifies the folder layout and compliance of the files with the TTL standard.
    2.5.2Ontology Hub (only for Core Service Provider)MUST offer a public raw http/get access to the Catena-X ontologyCAB uses an http client such as curl to test the raw file access and checks the file for compliance with the TTL standard.
    2.5.3Ontology Hub (only for Core Service Provider)MUST be able to host Ontology and Use Case models along the CX Ontology StandardSee CX-0067
    CAB uploads a reference set of ontology and use case models.
    + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +- CX-0018 Dataspace Connectivity v3.0.0 +- CX-0067 Ontology Models to realize federated query in Catena-X v1.1.0 +- [OWL 2 Web Ontology Language Profiles (Second Edition)](https://www.w3.org/TR/owl2-profiles/) +- [SPARQL 1.1 Query Language](https://www.w3.org/TR/sparql11-query/) +- [SPARQL Query Results JSON Format](https://www.w3.org/TR/sparql11-results-json/) +- [SPARQL Query Results XML Format](https://www.w3.org/TR/rdf-sparql-XMLres/) +- [Turtle - Terse RDF Triple Language](https://www.w3.org/TeamSubmission/turtle/) +- [Functional Requirements for Internet Resource Locators](https://www.rfc-editor.org/rfc/rfc1736) +- [Functional Requirements for Unique Resource Names](https://www.rfc-editor.org/rfc/rfc1737) +- [Uniform Resource Locators](https://www.rfc-editor.org/rfc/rfc1738) +- [Internationalized Resource Identifiers](https://www.rfc-editor.org/rfc/rfc3987) +- [git/http](https://www.git-scm.com/docs/http-protocol) + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- CX-0059 Use Case Behaviour Twin Endurance Predictor v1.3.0 +- [W3C Semantic Web Body of Standards](https://www.w3.org/2001/sw/wiki/Main_Page) +- [SPARQL Query Results CSV/TSV Format](https://www.w3.org/TR/sparql11-results-csv-tsv/) +- [Eclipse RDF4J Framework](https://rdf4j.org/) +- [Ontop Virtual Knowledge Graphs](https://ontop-vkg.org) + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +The [Knowledge Agents EDC](https://github.com/eclipse-tractusx/knowledge-agents-edc) presents a reference implementation that satisfies the [EDC](#21-cac-for-edc), [Matchmaking Agent](#22-cac-for-matchmaking-agent) and [Federated Catalogue](#23-cac-for-federated-catalogue) criteria. + +The [Knowledge Agents](https://github.com/eclipse-tractusx/knowledge-agents) presents reference implementations that satisfy the [Binding Agents](#24-cac-for-binding-agents) criteria. + +The [Ontology repository](https://github.com/eclipse-tractusx/ontology-models) and its redirection over https://w3id.org/catenax presents a reference implementation that satisfies the [Ontology Hub](#25-cac-for-ontology-hub) criteria. + +## ANNEXES + +### SPARQL Profiles + +The SPARQL Protocol And RDF Query Language is a query language and protocol for the Semantic Web. SPARQL provides powerful constructs to search, filter, traverse and even update globally dispersed information written in the Resource Description Framework. In particular, it operates very well with self-contained sources which have been modelled using the Web Ontology Language OWL2. + +OWL2 provides several profiles (language restrictions and/or computational barriers) with decreasing degrees of complexity and expressivity: RL (rule logic), EL (existential logic) and QL (query logic). The lower the degree, the more reasoning engines are likely to support the given profile in practical applications. + +In that tradition, this document proposes three profiles for SPARQL + +- KA-BIND for binding large-volume (virtual) data lakes and API gateways to RDF processing +- KA-MATCH building on KA-BIND for orchestrating non-trivial computations on the individual and sovereign RDF processors +- KA-TRANSFER for tunneling KA-MATCH invocations through inter-company HTTP proxy infrastructure + +These profiles are meant to standardize the usage of SPARQL as a scripting language in Dataspaces. + +Dataspaces are a peer-to-peer technology and requires to form contract agreements between multiple parties based on the actual data chains. + +In Catena-X, for example, a Dataspace that is based on IDS/GAIA-X infrastructure, these data chains follow the deep supply chains of the Automotive Industry in order to derive previously impossible use cases in the areas of Traceability, Distributed Simulation, etc. + +The profiles defined in this document are implemented in the [KA API specification](https://eclipse-tractusx.github.io/docs-kits/next/kits/knowledge-agents/development-view/api) + +![sparql_profiles.drawio.svg](./assets/sparql_profiles.drawio.svg) + +***Figure 4: SPARQL profiles*** + +#### KA-BIND + +KA-BIND restricts [SPARQL 1.1](https://www.w3.org/TR/sparql11-query/) in the following manner + +- POST-GET: the endpoint should support the http verbs POST and GET +- CONTENT-TYPE: the endpoint should support at least "application/sparql-result+json" (default) and "application/sparql-result+xml" media types in its responses (and resolve the request Accepts header accordingly). The endpoint should support the "application/sparql-query" media type. +- ONLY-SELECT: only the Query Form SELECT is supported +- OWL-QL: only interoperates with the OWL2 QL profile +- DEFAULT-GRAPH: operates only on the default graph: No graph references (no GRAPH contexts, no FROM or TO clauses) +- NO-FEDERATION: no federation, i.e. interaction with remote services (no SERVICE contexts) +- BOUND-PREDICATES: no variables in the predicate of triple patterns +- NO-LITERAL-SUBJECT: no literals in the subject of triple patterns +- BOUND-TYPE-OBJECT: if the predicate is rdf:type/a then the object cannot be a variable +- NO-INVERSE: no inverse predicates (InversePath) +- NO-TRANSITIVITY: no transitive predicates (OneOrMorePath, ZeroOrMorePath, ZeroOrOnePath) +- NO-NEGATION: no negated predicates (NegatedPath) +- NO-BLANK-SOURCE-NODE: no blank nodes in the source documents (but working with anonymous nodes in the query is still allowed) + +##### KA-BIND-F + +KA-BIND-F (Function Restricted KA-BIND) restricts KA-BIND in the following manner: + +- VALUES_STATEMENTS: The WHERE body of the SELECT query must consist of a (possibly empty) series of VALUES statements followed by a (possibly empty) series of triple patterns. + +#### KA-MATCH + +Let DRN (Dataspace Resource Name) be the subset of URN (Unique Resource Name which is a subset of IRI - Internationalized Resource Identifier) that denotes assets in the Dataspace. Examples in long and short-form are + +```console +GraphAsset?oem=Telematics2022 +https://w3id.org/catenax/ontology/common#GraphAsset?oem=Telematics2022 +SkillAsset?oem=ListVehicles +https://w3id.org/catenax/ontology/common#SkillAsset?oem=ListVehicles +``` + +GDRN (Graph Dataspace Resource Name) is the subset of DRN which denote proper graph assets. + +SDRN (Skill Dataspace Resource Name) is the subset of DRN which denote skill assets. + +Let DRL (Dataspace Resource Locator) be the subset of URL (Unique Resource Locator which is also a subset of IRI) that denotes connector addresses in the Dataspace. For that purpose, we introduce the schemes "edc" and "edcs" meaning that a party has to apply the proper dataspace protocols (which could be transferred via http or https respectively) in order to manage and access the resources under these addresses. + +Examples are + +```console +edc://private.connector:8282 +edcs://public.connector/protocol +``` + +If the DRL contains with an anchor part (#), we call the DRL qualified and that anchor part must url-encode a valid DRN. + +Examples are + +```console +edc://private.connector:8282#GraphAsset%3Foem%3DTelematics2022 +edcs://public.connector/protocol#SkillAsset%3Foem$3DListVehicles +edcs://public.connector/protocol#SkillAsset%3Foem$3DListVehicles?productionDate=2023&(vehicleSeries=213&vehicleSeries=215) +``` + +If the DRL contains parameters, the "(" character is only allowed in the beginning of parameter keys, the ")" character is only allowed at the end of parameter values. Opening and closing parenthesis +need to match. + +KA-MATCH restricts [SPARQL](https://www.w3.org/TR/sparql11-query/) in the following manner + +- LIMITED-FEDERATION: any SERVICE context which binds to a DRL + - if the DRL is unqualified, it must have EXACTLY ONE GRAPH sub-context which points to a GDRN. You may use only KA-BIND inside of that GRAPH context. + - If the DRL is qualified: + - if it anchors a SDRN then the context must only contain a sequence of BIND statements, because the SERVICE represents a (multi-valued) skill call. + - it must NOT have ANY GRAPH sub-context. You may use only KA-BIND inside of the service context. +- OWL-EL: only interoperates with the OWL2 EL profile +- LIMITED-GRAPH: GRAPH references (FROM, TO or GRAPH contexts) must point to a GDRN or qualified DRL anchoring a GDRN. +- NO-LITERAL-SUBJECT: no literals in the subject of triple patterns + +KA-MATCH extends SPARQL in the following manner + +- POST-GET-OPTIONS: the endpoint should support the http verbs POST, GET and OPTIONS - the latter for the purpose to control cross-domain scripting (which is optional, so returning an error status is sufficient). +- POST-SKILL: There MUST be a sub-path "/skill" to the SPARQL endpoint which accepts a non-empty body of media type "application/sparql-query" and contains a valid KA-MATCH SPARQL text. It also requires a query parameter "asset" which is a valid SDRN. It returns a success code when these conditions are met and the text could be successfully stored. In that case, you may use the asset SDRN (for example as the anchor of a qualified DRL) in future GET and POST calls. The query text can contain variable references. +- ASSET-TARGET: In both the GET and POST Http Verbs, you may use the query parameter "asset" which should be set to some qualified DRL (global dataspace asset) or DRN (local asset). If the body of the request (POST) or the query parameter (POST or GET) is a valid SPARQL query (media type "application/sparql-query") then the asset MUST anchor a valid GDRN (in which case the query should be executed as if the TO/FROM clause would be set to the GDRN). Otherwise, the asset MUST anchor a valid SDRN (in which case the previously store query text from POST-SKILL is executed). We call the query text from either the query parameter (GET), the body (POST) or the skill asset lookup (GET and POST) the resolved query. +- PARAMETRIZED-QUERY: The resolved query may contain variable references (literals or iris starting with @ e.g., "@troubleCode"^^xsd:string or \<@vin^^cx:Vehicle\>). For each referenced variable, there must be either at least one correspondingly-named query parameter (GET, POST) or the media type of the body (POST) is one of "application/sparql-results+json" or "application/sparql-results+xml" and the variable is bound there. For variables bound as query parameters, there is the option to build tuple-based combinations by using open parentheses as the prefix of a variable/parameter name "(" and a closing parentheses ")" as the suffix of a substitution. +- RUN-MODE: In combination with ASSET-TARGET, the query parameter "runMode" can be used and take any of three values "consumer", "provider" or "all" (which is the default). This determines the preferred execution location of the protocol and may result in an error (Status Code \>=400 and \<500) depending on the actual contracts and policies associated to the affected asset. +- QUERY-LANG: The query parameter "queryLn" can be used, but is currently fixed to the value "SPARQL". +- WARNINGS: KA-MATCH may indicate a successful result that has been generated with additional warnings regarding the execution with the status code "203". Both in that case as well as in case of technically unsuccessful calls (Status Code \<200 or \>299), a response header “cx_warning” bound to a JSON structure that lists abnormal events or trace information that appeared during the processing. + +The cx_warning JSON structure is a list of objects which contain at least the following properties + +- source-tenant +- source-asset +- target-tenant +- target-asset +- problem +- context + +```csharp +[{"source-tenant":"http://consumer-control-plane:8181/management","source-asset":"urn:x-arq:DefaultGraph","target-tenant":"edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN","target-asset":"GraphAsset?oem=Telematics20222","problem":"Failure invoking a remote batch: Result may be partial.","context":"1414472378"}] +``` + +Depending on data sovereignty rules, the individual fields may be shaded or replaced by pseudonyms such that they could be looked up via different (organizational) +channels if needed. + +#### KA-TRANSFER + +KA-TRANSFER is a variant of KA-MATCH which allows to proxy the payloads over headerless or fixed-header protocols by implementing the following "WRAP-HEADERS" strategy: + +| KA-MATCH Component | KA-MATCH Name | KA-TRANSFER Component | KA-TRANSFER Name | Description | +|--------------------|-----------------|----------------------------|---------------|-------------| +| Request Header | Accept | Request URL Query Parameter| cx_accepts | This header is integral part of the protocol, since federating agents may require a particular result format in their internal processing. | +| Response Header | cx_warnings | Response multi-part body | cx_warnings | This header is integral part of the protocol in order to annotate and analyze a robust distributed processing which is always subject to unforeseen failures. | + +### Agent-Related EDC Assets + +In the following, we describe the convention how agent-related assets should be defined and represented in EDC. + +Agent-related assets are + +- Graph Assets: Assets providing access to a binding agent. We recommend to start the identification of each graph asset using the prefix "GraphAsset". +- Skill Assets: Assets providing access to logic that is stored in the matchmaking agent. We recommend to start the identification of each skill asset using the prefix "SkillAsset". + +Since asset ids are used in some technical background, they should not contain colons (' : '), we recommend to identify them via url-type parameters, e.g., "GraphAsset?owner=content&property=value". + +The asset definition in EDC is formulated in [JSON-LD](https://json-ld.org/) and consists of two parts: + +- the "asset" part containing a description that is part of any published/offered catalogue that contains the asset. +- the "dataAddress" part containing EDC internal routing configuration for performing data transfers from/to the asset. + +The following is an example of a valid graph asset definition. +Please note that due to technical reasons, a valid definition needs to carry redundant information (such as about the type of asset) in order to mitigate version upgrades in the Catena-X standard body. + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cs-taxo": "https://w3id.org/catenax/taxonomy#", + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#", + "rdfs": "http://www.w3.org/2000/01/rdf-schema#", + "sh": "http://www.w3.org/ns/shacl#", + "dct": "https://purl.org/dc/terms/" + }, + "@type": "Asset", + "@id": "cx-taxo:GraphAsset?supplier=BehaviourTwinRUL", + "properties": { + "cx-common:name": "Lifetime Prognosis Service for Gearboxes", + "cx-common:description": "A sample graph asset/offering referring to a specific prognosis resource.", + "cx-common:description@de": "Ein Beispielasset für eine Prognosefunktion.", + "cx-common:version": "1.11.16", + "cx-common:contenttype": "application/json, application/xml", + "cx-common:publishedUnderContract": "Contract?supplier=Graph", + "dct:type": "cx-taxo:GraphAsset", + "rdfs:isDefinedBy": ",,,,", + "cx-common:implementsProtocol": "cx-common:Protocol?w3c:http:SPARQL", + "sh:shapesGraph": + "@prefix rdf: . + @prefix rdfs: . + @prefix schema: . + @prefix sh: . + @prefix xsd: . + @prefix edc: . + @prefix cx-common: . + @prefix cx-core: . + @prefix cx-vehicle: . + @prefix cx-fx: . + @prefix cx-behaviour: . + @prefix cx-reliability: . + @prefix cx-sh: . + @prefix cx-taxo: . + @prefix : . + + :LoadSpectrumShape a sh:NodeShape ; + sh:targetClass cx-reliability:LoadSpectrum; + sh:property :observationOfShape, + :countingValueShape, + :countingUnitShape, + :countingMethodShape, + :channelsShape, + :classesShape, + :valuesShape. + + :observationOfShape a sh:PropertyShape; + sh:path cx-reliability:observationOf; + sh:in (cx-taxo:GearOil cx-taxo:GearSet cx-taxo:Clutch). + + :countingValueShape a sh:PropertyShape; + sh:path cx-reliability:countingValue. + + :countingUnitShape a sh:PropertyShape; + sh:path cx-reliability:countingUnit. + + :countingMethodShape a sh:PropertyShape; + sh:path cx-reliability:countingMethod. + + :countingMethodShape a sh:PropertyShape; + sh:path cx-reliability:countingMethod. + + :channelsShape a sh:PropertyShape; + sh:path cx-reliability:channels. + + :classesShape a sh:PropertyShape; + sh:path cx-reliability:classes. + + :valuesShape a sh:PropertyShape; + sh:path cx-reliability:values.", + "cx-common:isFederated": "true^^xsd:boolean" + }, + "dataAddress": { + "id": "cx-taxo:GraphAsset?supplier=BehaviourTwinRUL", + "@type": "DataAddress", + "baseUrl": "{{tierARemotingAgent}}/repositories/rul", + "type": "cx-common:Protocol?w3c:http:SPARQL", + "proxyPath": "false", + "proxyMethod": "true", + "proxyQueryParams": "true", + "proxyBody": "true", + "authKey": "{{supplierBackendAuthKey}}", + "authCode": "{{supplierBackendAuthCode}}", + "cx-common:allowServicePattern": "{{tierARemotingAgent}}/repositories/rul" + } + } + +``` + +#### Common Asset Properties + +In particular, the "asset" part of each asset description has a natural correspondence in the RDF representation of the Federated Catalogue. To +define this correspondence in the following, we assume the following prefix abbreviations to denote complete IRIs. + +| Prefix | Namespace | Property Domain | +|-----------|------------------------------------------------------|--------------------------------| +| edc | https://w3id.org/edc/v0.0.1/ns/ | EDC annotations | +| rdf | http://www.w3.org/1999/02/22-rdf-syntax-ns# | RDF type annotations | +| rdfs | http://www.w3.org/2000/01/rdf-schema# | RDF schema annotations | +| dct | https://purl.org/dc/terms/# | Dublin Core annotations | +| owl | http://www.w3.org/2002/07/owl# | OWL model annotations | +| xsd | http://www.w3.org/2001/XMLSchema# | XML schema annotations | +| json | https://json-schema.org/draft/2020-12/schema# | JSON schema annotations | +| sh | http://www.w3.org/ns/shacl# | SHACL constraints | +| cx-common | https://w3id.org/catenax/ontology/common# | Catena-X common annotations | +| cx-taxo | https://w3id.org/catenax/taxonomy# | Catena-X taxonomy declarations | + +The "asset" part itself mainly consists of a "properties" section which is a set of string-based key-value pairs. +In the following table, we list those keys which are of relevance for both Graph and Skill Assets and hence are mapped to an RDF expression. + +| Property Key | Mandatory | Description | RDF Representation | Example Property Value | +|--------------|-----|----------------------------------|--------------------------------------------|------------------------------------------------------| +| edc:id, @id | yes | Plain Id of the Asset | BIND(<value> as ?asset). ?asset cx-common:id "value". | GraphAsset?oem=TelematicsSample | +| edc:name | yes | Default Name of the Asset | ?asset cx-common:name "value"^^xsd:string. | Telematics Data 2022 | +| edc:name@de | no | German Name of the Asset | ?asset cx-common:name "value"^^xsd:string@de. | Telematik Daten 2022 | +| edc:description | no | Default Description of the Asset | ?asset cx-common:description "value"^^xsd:string. | Telematics Data for Series 213 from 20022 | +| edc:description@de| no | German Description of the Asset | ?asset cx-common:description "value"^^xsd:string@de. | Telematik Daten für BR 213 aus 20022 | +| edc:contenttype | yes | Mime Type of Asset response | ?asset cx-common:contentType "value". | application/sparql-results+json, application/sparql-results+xml | +| dct:type | yes | Type IRI of the asset | ?asset dct:type <value>.| cx-taxo:GraphAsset for Graphs, cx-taxo:SkillAsset for Skills| +| rdfs:isDefinedBy | yes | Use Case / Domain Ontology IRIs | ?asset rdfs:isDefinedBy value.| https://w3id.org/catenax/usecase/behaviourtwin | +| cx-common:version | no | Version of the Asset | ?asset cx-common:version "value". | 1.9.3-SNAPSHOT (Prefix changed in 1.1.0 from edc:version)| +| cx-common:implementsProtocol | yes | Asset Protocol IRI | ?asset cx-common:implementsProtocol <value>. | cx-common:Protocol?w3c:http:SPARQL | +| cx-common:publishedUnderContract | no | Contract IRI | ?asset cx-common:publishedUnderContract <value>. | Contract?oem=GraphContract | +| cx-common:satisfiesRole | yes | Use Case Role IRI | ?asset cx-common:satisfiesRole <value>. | Role?oem=BehaviourTwin | +| cx-common:isFederated | yes | Determines whether this asset should be synchronized in the Federated Catalogue | ?asset cx-common:protocol value. | true^^xsd:boolean | + +#### Graph Assets and Addresses + +Graph assets need a asset content description in terms of the constraint language [SHACL](https://www.w3.org/TR/shacl/) + +| Property Key | Mandatory | Description | RDF Representation | Example Property Value | +|--------------|-----|----------------------------------|--------------------------------------------|------------------------------------------------------| +| sh:shapesGraph | yes | SHACL Description of Graph | ?asset sh:shapesGraph <graph>. (where the constraints can be accessed via GRAPH <graph> {}) | SHACL TTL | + +The "dataAddress" part for Graph Assets also consists of a set of string-based key-value pairs. Since that part is not public, it will not have an RDF representation. +In the following table, we list those keys which are of relevance for Graph Assets. + +| Property Key | Mandatory | Description | Example Property Value | +|--------------|-----|----------------------------------|--------------------------------------------| +| edc:id | yes | Plain Id of the Graph Asset must coincide with @id and edc:id of "asset" part | GraphAsset?oem=TelematicsSample | +| edc:type | yes | Asset Protocol IRI must coincide with cx-common:implementsProtocol of "asset" part | cx-common:Protocol?w3c:http:SPARQL | +| edc:baseUrl | yes | URL of the binding Agent | https://knowledge.dev.demo.catena-x.net/conforming-agent/bind | +| edc:proxyPath | yes | must be set to “false” | false | +| edc:proxyMethod | yes | must be set to “true” | true | +| edc:proxyQueryParams | yes | must be set to "true" | true | +| edc:proxyBody | yes | must be set to "true" | true | +| edc:authKey | no | optional authentication header | X-Api-Key, Authorization | +| edc:authCode | no | optional authentication value | my-api-key, Basic Adm9axmJhcg== | +| cx-common:acceptsContentType | no | optional fixed Accepts header forwarded to the endpoint | application/sparql-results+json | + +#### Skill Assets and Addresses + +The following is an example of a Skill Asset. + +```json +{ + "@context": { + "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#", + "rdfs": "http://www.w3.org/2000/01/rdf-schema#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "dct": "https://purl.org/dc/terms/", + "sh": "http://www.w3.org/ns/shacl#" + }, + "properties": { + "name": "Lists Vehicles By Production Date and Series", + "description": "A sample skill asset/offering operating on vehicle/part ontology.", + "cx-common:version": "1.9.3-SNAPSHOT", + "contenttype": "application/json, application/xml", + "cx-common:publishedUnderContract": "Contract?oem=Skill", + "dct:type": { + "@id": "cx-taxo:SkillAsset" + }, + "rdf:type": "cx-common:SkillAsset", + "rdfs:isDefinedBy": ",,,,", + "cx-common:implementsProtocol": "cx-common:Protocol?w3c:http:SKILL", + "cx-common:distributionMode": "cx-common:SkillDistribution?run=all", + "cx-common:isFederated": "true^^xsd:boolean" + }, + "privateProperties": { + "cx-common:query":"SELECT ?s WHERE { ?s a ; ?date. FILTER(year(?date) = \"@productionYear\"^^xsd:integer.)}" + }, + "dataAddress": { + "id":"SkillAsset?oem=ListVehicles", + "@type": "DataAddress", + "type": "cx-common:Protocol?w3c:http:SKILL", + "proxyPath": "false", + "proxyMethod": "true", + "proxyQueryParams": "true", + "proxyBody": "true" + } +} +``` + +Skill assets need a public self-description which determines whether the skill can be invoked locally (at the site of the consumer), remotely (at the site of the provider) or both + +| Property Key | Mandatory | Description | RDF Representation | Example Property Value | +|--------------|-----|----------------------------------|--------------------------------------------|------------------------------------------------------| +| cx-common:distributionMode | yes | Distribution mode of the skill | ?asset cx-common:distributionMode <value> | cx-common:SkillDistribution?run=provider
    cx-common:SkillDistribution?run=consumer
    cx-common:SkillDistribution?run=all | + +Please note that according to the mirroring roles of provider and consumer, the "cx-common:distributionMode" setting mirrors the approriate "runMode" query parameter (RUN-MODE) in the KA-MATCH protocol profile. +That is, a "runMode=consumer" invocation requires a "cx-common:distributionMode" of "cx-common:SkillDistribution?run=consumer" or "cx-common:SkillDistribution?run=all". +A "runMode=provider" invocation requires a "cx-common:distributionMode" of "cx-common:SkillDistribution?run=provider" or "cx-common:SkillDistribution?run=all". +A "runMode=all" will resolve to "runMode=consumer" if "cx-common:distributionMode" is set to "cx-common:SkillDistribution?run=consumer". +It will resolve to "runMode=provider" if "cx-common:distributionMode" is set to "cx-common:SkillDistribution?run=provider". +Else it will resolve to either "runMode=consumer" or "runMode=provider" depending on the consumer preferences/configuration. + +Skill assets also use the "privateProperties" section of the "asset" definition which is a set of string-based key-value pairs that is only visible to the publisher. + +| Property Key | Mandatory | Description | RDF Representation | Example Property Value | +|--------------|-----|----------------------------------|--------------------------------------------|------------------------------------------------------| +| cx-common:query | yes | A valid KA-MATCH SPARQL query | SELECT ?s WHERE \{ ?s a \. \} | + +The "dataAddress" part for Skill Assets consists of the following properties. + +| Property Key | Mandatory | Description | Example Property Value | +|--------------|-----|----------------------------------|--------------------------------------------| +| edc:id | yes | Plain Id of the Skill Asset must coincide with @id and edc:id of "asset" part | SkillAsset?oem=ListVehicles | +| edc:baseUrl | yes | must be empty | | +| edc:proxyPath | yes | must be set to “false” | false | +| edc:proxyMethod | yes | must be set to “true” | true | +| edc:proxyQueryParams | yes | must be set to "true" | true | +| edc:proxyBody | yes | must be set to "true" | true‚ | + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/architecture.drawio.svg b/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/architecture.drawio.svg new file mode 100644 index 000000000..8b97e7c93 --- /dev/null +++ b/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
    Dataspace
    Dataspace
    Consumer A
    Consumer A
    Provider C
    Provider C
    Provider B
    Provider B
    Backend Database
    Backend Da...
    Backend Service
    Backend Se...
    2. Distribute/Delegate
    Sub-Skills
    2. Distribute/Delegate...
    EDC
    EDC
    Matchmaking
    Agent
    Matchmaking...
    Binding Agent
    Binding Agent
    1.Invoke Skill
    (Procedure)
    1.Invoke Skill...
    Data Consuming
    App
    Data Consuming...
    Binding Agent
    Binding Agent
    EDC
    EDC
    3. Authorize to Graph Asset
    3. Authorize to Graph Asset
    Matchmaking
    Agent
    Matchmaking...
    EDC
    EDC
    Matchmaking
    Agent
    Matchmaking...
    4. Translate Into
    Efficient Backend Operations
    4. Trans...
    5. Federate Knowledge
    (Output Dataset)
    5. Federate Knowledge...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/dataspace_layer.drawio.svg b/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/dataspace_layer.drawio.svg new file mode 100644 index 000000000..97553702b --- /dev/null +++ b/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/dataspace_layer.drawio.svg @@ -0,0 +1,4 @@ + + + +
    Binding Layer
    Binding Layer
    Data Consumption Layer/Query Definition
    Data Consumption Layer/Query Definition
    Transfer
    Initiation
    /Validation
    Transfer...
    EDC Control Plane
    EDC Control Plane
    Management/Catalogue API
    Management/Catalogue API
    Federated 
    Catalogue
    Federated...
    Core Services
    Core Services
    RDF
    Storage
    (e.g.
    SAIL)
    RDF...
    Matchmaking
    Agent
    Matchmaking...
    git/http
    Download
    On
    Init
    git/http...
    KA-MATCH SPARQL Profile
    KA-MATCH S...
    KA-BIND SPARQL Profile
    KA-BIND SP...
    Dataspace
    Layer
    Dataspac...
    EDC Data Plane(s)
    EDC Data Plane(s)
    Semantic Model
    Semantic Model
    GPDM
    GPDM
    Self-Description Hub
    Self-Description H...
    Endpoint Callback
    Endpoint C...
    Management/Asset API
    Management...
    Invoke (Sink)
    KA-TRANSFER
    Invoke (Sink)...
    (Source)
    Delegate KA-TRANSFER
    SPARQL Profile
    (Source)...
    Transfer Negotiation
    Transfer N...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/layer_architecture.drawio.svg b/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/layer_architecture.drawio.svg new file mode 100644 index 000000000..e21d17cc8 --- /dev/null +++ b/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/layer_architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
    Data Virtualization Layer
    Data Virtualization Layer
    Backend Systems
    Backend Systems
    ERP
    ERP
    PLM
    PLM
    Network Appliance
    Network Ap...
    AAS
    AAS
    Binding Layer
    Binding Layer
    Dataspace Layer
    Dataspace Layer
    Data Consumption Layer/Query Definition
    Data Consumption Layer/Query Definition
    EDC* Control Plane
    Data Plane(s)
    EDC* Control Plane...
    Federated 
    Catalogue
    Federated...
    Graph Database
    Graph Database
    Virtual Knowledge
    Graph
    Virtual Knowledge...
    API Gateway
    API Gateway
    Data Consuming
    App
    Data Consuming...
    Skill
    Framework
    Skill...
    Query/Skill
    Editor
    Query/Skill...
    ETL/Data Lake
    ETL/Data Lake
    Functional
    Remoting
    Functional...
    Semantic Models
    Semantic Models
    Ontology
    Management
    Ontology...
    Ontology
    Visualization & Editing
    Ontology...
    Matchmaking
    Agent
    Matchmaking...
    OWL
    TTL
    git
    OWL...
    SPARQL
    http/s
    SPARQL...
    SQL
    REST
    SQL...
    (B)API
    FS
    (B)API...
    Object Store
    Object Store
    Development Tools
    Development Tools
    Use Case 
    Tooling
    Use Case...
    Business Partner 
    Tooling
    Business Partner...
    Test Tooling
    Test Tooling
    CX Release 23.12 (CX-0084 1.1.0)
    CX Release 23.12 (CX-0084 1.1.0)
    AAS REST API
    AAS REST API
    KA-AAS Bridge
    KA-AAS Bridge
    AAS-KA Bridge
    AAS-KA Bridge
    other
    other
    planned for CX Release 24.X
    planned for CX Release 24.X    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/sparql_profiles.drawio.svg b/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/sparql_profiles.drawio.svg new file mode 100644 index 000000000..48165053d --- /dev/null +++ b/docs/standards/CX-0084-FederatedQueriesInDataSpaces/assets/sparql_profiles.drawio.svg @@ -0,0 +1,4 @@ + + + +
    KA-BIND
    KA-BIND
    KA-TRANSFER
    KA-TRANSFER
    «interface»
    Matchmaking Agent
    «interface»...
    «interface»
    Eclipse Dataspace
    Connector
    «interface»...
    «interface»
    Binding Agent
    «interface»...
    KA-MATCH
    KA-MATCH
    User / Application
    User...
    «interface»
    Remoting 
    (Function Binding)
    Agent 

    «interface»...
    KA-BIND-F
    KA-BIND-F    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0094-AspectModelPartSiteInformationAsPlanned/CX-0094-AspectModelPartSiteInformationAsPlanned.md b/docs/standards/CX-0094-AspectModelPartSiteInformationAsPlanned/CX-0094-AspectModelPartSiteInformationAsPlanned.md new file mode 100644 index 000000000..4be1bf51e --- /dev/null +++ b/docs/standards/CX-0094-AspectModelPartSiteInformationAsPlanned/CX-0094-AspectModelPartSiteInformationAsPlanned.md @@ -0,0 +1,213 @@ +# CX-0094 Aspect Model: Part Site In Formation As Planned v1.0.0 + +## ABSTRACT + +The semantic model described below describes a submodel for a digital twin on material or part level providing site related information. A site is a delimited geographical area where a legal entity does business. In the Digital Twin as planned lifecycle stage all potentially related sites are listed including all sites where e.g. production of this material or part is planned. + +## 1. INTRODUCTION + +The aspect PartSiteInformationAsPlanned provides site related information for a given as planned item (i.e. a part type that is uniquely identifiable within Catena-X via its Catena-X ID). A site is a delimited geographical area where a legal entity does business. In the "as planned" lifecycle context all potentially related sites are listed including all sites where e.g. production of this part is planned. + +Note: The presented aspect model is in version 1.0.0 + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard applies to the roles: + +1. Data Provider / Consumer +2. Business Application Provider + +The described semantic model or submodel template must be provided by applications provisioning data for the Digital Twin AsPlanned lifecycle as well as all data providers in the Digital Twin AsPlanned lifecycle. + +### 1.2 CONTEXT + +> *This section is non-normative* + +This submodel template or aspect model is required to give site related information for a given part. + +Therefore this aspect contains information at which different locations (sites) a planned part is processed, e.g. from design to production of a part. + +### 1.3 ARCHITECTURE OVERVIEW + +> *This section is non-normative* + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, +examples, and notes in this specification are non-normative. Everything else in +this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, +**REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be +interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they +appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants* and their solutions must prove they conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +The proof of conformity for a single semantic model is done according to the general rules for proving the conformity of data provided to a semantic model or the ability to consume the corresponding data. + +**Disclaimer: The operating model released by the Catena-X association will define the roadmap, content and scope for the certification process. This will include the roles, certification and further assessment procedures as well as the rollout phases*. + +### 1.6 EXAMPLES + +Example JSON payload: Submodel "PartSiteInformationAsPlanned" for a component that is produced at the given site + +```json +{ + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "sites": [ + { + "catenaXSiteId": "BPNS1234567890ZZ", + "functionValidUntil": "2025-11-21T11:14:30.825+01:00", + "function": "production", + "functionValidFrom": "2022-11-21T11:14:30.825+01:00" + } + ] +} +``` + +### 1.7 TERMINOLOGY + +> *This section is non-normative* + +> Aspect Model +: a formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect. + +: Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model. + +: Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +*[Source: Catena-X, CX-0002, note 3 removed]* + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 ASPECT MODEL “PartSiteInformationAsPlanned” + +> *This section is normative* + +This semantic model contains information at which locations (sites) a planned part will be processed. For representing sites only BusinessPartnerNumberSites may only be used. The original intent is to attach this aspect to a material specific twin in an Asset Administration Shell but is not limited to that use case. + +This aspect may only contain BusinessPartnerNumberSites. In the As-Planned lifecycle state all variants are covered ("120% BOM"). + +Every data provider of partSiteInformationAsPlanned data MUST provide the data conformant to the semantic model specified in this document. + +The unique identifier of the semantic model specified in this document MUST be used by the data provider to define the semantics of the data being transferred. + +Every certified business application relying on partSiteInformationAsPlanned data MUST be able to consume data conformant to the semantic model specified in this document. + +This semantic model **MUST** be made available in the central Semantic Hub. + +Data consumers and data provider **MUST** comply with the license of the semantic model. + +The submodel data **MUST** be transferred using the IDS Protocol as described in CX-0018 and CX-0002. + +Data providers **MUST** provide the data as part of a digital twin of the asset for a material/plant conformant to CX-0002. + +The JSON Payload of data providers **MUST** be conformant to the JSON Schema as specified in this document. + +### 2.1 INTRODUCTION + +The aspect PartSiteInformationAsPlanned provides site related information for a given as planned item (i.e. a part type that is uniquely identifiable within Catena-X via its Catena-X ID). A site is a delimited geographical area where a legal entity does business. In the "as planned" lifecycle context all potentially related sites are listed including all sites where e.g. production of this part is planned. + +Note: The presented aspect model is in version 1.0.0 + +### 2.2 SPECIFICATION ARTIFACTS + +The modeling of the semantic model specified in this document was done in +accordance to the "semantic driven workflow" to create a submodel template +specification [SMT](#32-non-normative-references). + +This aspect model is written in SAMM 2.0.0 as a modeling language conformant to CX-0003 +as input for the semantic deriven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub2F2F +conformant to CX-0003. + +### 2.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. + +### 2.4 IDENTIFER OF SEMANTIC MODEL + +The semantic model has the unique identifier: + +```text +urn:bamm:io.catenax.part_site_information_as_planned:1.0.0 +``` + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +### 2.5 FORMATS OF SEMANTIC MODEL + +#### 2.5.1 RDF Turtle + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating +additional file formats and serializations. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.part_site_information_as_planned/1.0.0/PartSiteInformationAsPlanned.ttl +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +#### 2.5.2 JSON Schema + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +#### 2.5.3 aasx + +A AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#32-non-normative-references)]. + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +CX-0002 DIGITAL TWINS IN CATENA-X + +CX-0003 BAMM Aspect Meta Model + +CX-0004 GOVERNANCE PROCESS + +CX-0018 ECLPISE DATA SPACE CONNECTOR (EDC) + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +[SMT] How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +```text + [OPTIONAL] Add figures here if nececarry +``` + +### TABLES + +> *This section is non-normative* + +```text + [OPTIONAL] Add Tables here here if nececarry +``` + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0102-Functional-Mock-Up/CX-0102-Functional-Mock-Up.md b/docs/standards/CX-0102-Functional-Mock-Up/CX-0102-Functional-Mock-Up.md new file mode 100644 index 000000000..131d5f554 --- /dev/null +++ b/docs/standards/CX-0102-Functional-Mock-Up/CX-0102-Functional-Mock-Up.md @@ -0,0 +1,120 @@ +# CX-0102 Functional Mock Up v1.0.0 + +## ABSTRACT + +The goal of this Catena-X standard is to make an existing industry standard available in the Catena-X Network. This document provides an overview of the standard as well as the relevant links to the online documentation. +FMI (functional mockup interface) is a free cross-industry standard to exchange dynamic simulation models. +The vision of FMI is to improve the design of systems and embedded software in vehicles. As a real product can be decomposed into different parts interacting with each others and each performing specific tasks, so the model of the product can be decomposed into sub-systems interacting with each others each described by a set of physical equations. The FMI standard provides the means to support model based development by defining ways in which models of systems and subsystems can be exchanged and connected with each other. +The FMI standard is key for the interoperability of simulation tools. It is supported by more than 170 tools, both proprietary and open-source. The FMI specifications are published under the CC-BY-SA 4.0 (Creative Common Attribution-ShareAlike 4.0 International) license. Source code, such as C-header and XML-schema files, that accompany specification documents, are provided under the 2-Clause BSD License. + +## FOR WHOM IS THE STANDARD DESIGNED + +The standard is designed by the Modelica Association Project for anybody who wants to build, use and exchange dynamic simulation models. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +Not relevant + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This Standard is relevant for: + +- Data Provider / Consumer +- Enablement Service Provider +- Consulting Services Provider + +The standard is relevant for modeling of physical assets. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +CX - 0102 FUNCTIONAL-MOCK-UP v1.0.0 + +The Functional Mock-up Interface (FMI) is a free standard that defines a container and an interface to exchange dynamic simulation models using a combination of XML files, binaries and C code, distributed as a ZIP file. It is supported by 170+ tools and maintained as a Modelica Association Project. The FMI implementation by a software modelling tool enables the creation of simulation models that can be interconnected. The file format of the FMI standard is called Functional Mock-up Unit (FMU) (source: https://fmi-standard.org/). +In the context of Catena-X, simulation models can represent for example a component of a vehicle produced by a Tier-1. The Tier-1 develops the model of its component using any FMI compatible tool. The model is then exported as FMU. The model is now packed as a black box model. The person (for example from an OEM) who receives the simulation model can only see the input and output ports and the parameters and variables of the models that have been exposed by the model creator. In this way the intellectual properties of the model creator is protected. +Using the FMU format, an OEM can get models of the components needed for its vehicle from different Tier-1s already in the design phase. The models are then integrated together with the own OEM's models to build a vechicle model. The assembled model is used to run parametric studies to assess the performace of the vehicle. The same workflow is also valid for a Tier-(N+1) and its Tier-Ns. +In a more general approach, FMUs can be seen as services providing an output for a given input. As such they can be used for data processing and analytics and as components of more complex services like the computation of Remaining Useful Life (RUL). + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +For the FMI format the conformity is relevant both, for tools exporting FMUs and for tools importing FMUs. For each type, different proof of conformity are used. To prove the conformity of a tool exporting FMUs one of the following criteria MUST be fulfilled: + +- Use one of the tools which exports FMUs among the ones listed on this page https://fmi-standard.org/tools/ +- If a new tool is used which is not part of the list, a set of FMUs exported by the tool MUST be validated using the validation tool provided here https://fmu-check.herokuapp.com/. The online validation tool takes an FMU as input and verifies that it is conform to the standard. +- If the tool is not part of the list a request to add it can be submitted by following the instruction on the page under the link "How do I add or update my tool?". Once the request is accepted, the tool is added to the list. + +To prove the conformity of a tool importing FMUs one of the following criteria MUST be fulfilled: + +- Use one of the tools which imports FMUs among the ones listed on this page https://fmi-standard.org/tools/. +- If the tool is not part of the list a request to add it can be submitted by following the instruction on the fmi page under the link "How do I add or update my tool". Once the request is accepted, the tool is added to the list. + +### 1.4 EXAMPLES + +When a FMU, generated from a tool, is verified for conformity using the https://fmu-check.herokuapp.com/, the following aspects are part of the check. +The following list is copied from the FMU check page. FMU Check performs a static analysis of the FMU that validates the following aspects: + +- validity of the modelDescription.xml w.r.t. the XML schema +- uniqueness and validity of the variable names +- completeness and integrity of the Model Structure +- availability of the required start values +- combinations of causality and variability +- definition of units + +It does not check the following aspects: + +- validity of the binaries +- validity of the sources +- any non-standard files inside the FMU + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +FMU = functional mock-up unit. A simulation model packed following the specification of the FMI industry standard. + +FMI = functional mock-up interface. Standard that defines an exchange format for dynamic simulation models. + +## 2 MAIN CONTENT + +> *This section is normative* + +The FMI standard is described and documented on the FMI website: https://fmi-standard.org/. At the moment there exist three versions of the FMI standard (FMI 1.0, 2.0 and 3.0) and they are all included in the Catena-X standard as well as future versions. Implementers Guide, Specification and Packages for each of the three versions can be downloaded on the website. The companies who want to use the FMI standard for their use cases MUST fullfill the criteria stated in the documentation provided on the link above. + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +Functional Mock-up Interface Standard - https://fmi-standard.org/ + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +Not relevant + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not relevant + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0105-AssetTrackingUseCase/CX-0105-AssetTrackingUseCase.md b/docs/standards/CX-0105-AssetTrackingUseCase/CX-0105-AssetTrackingUseCase.md new file mode 100644 index 000000000..8831ee86e --- /dev/null +++ b/docs/standards/CX-0105-AssetTrackingUseCase/CX-0105-AssetTrackingUseCase.md @@ -0,0 +1,1295 @@ + +# CX-0105 Asset Tracking Use Case v1.1.0 + +## ABSTRACT + +The asset tracking use case aims to design a standard solution how diverse IoT solutions, available on the free market, can be incorporated into the Catena-X network keeping the interoperability and data sovereignty requirements respected. Although the main goal was always to track company assets with the various IoT devices, based on the set of standards designed by asset tracking use case team, there is a potential to fully use these in any use case in the Catena-X environment and beyond. The model opens the door for any IoT device manufacturer and any network provider to be part of the Catena-X network. + +This standard focuses on the Asset Tracking Use Case. It includes relevant requirements for + +- ATP (Asset Tracking Platform) as sensor data provider +- Application/Dashboard as data consumer - non standardized tool + +## FOR WHOM IS THE STANDARD DESIGNED + +Please refer to: AUDIENCE & SCOPE. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +This is the initial version of the standard. + +## 1 INTRODUCTION + +This document defines the so-called standardization triangle for the asset tracking use case. +Standardization triangle hereby means the mandatory components, data models, and APIs that are required to enable the asset tracking use case. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This document is meant for the following roles: + +- Data Provider / Consumer +- Business Application Provider + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +The Asset Tracking Platform aims to bring different IoT sensor networks to a standard Catena-X network and use sensor data for a variety of use cases, like: + +- Logistics teams can track their returnable packages and assets at any time using geo data +- Use of automatic filling level measurements to drive efficient vendor-managed inventories +- Users (Tier suppliers, customers, carriers, insurers, etc.) are encouraged to monitor the quality of critical materials at any time during transportation + +## Asset Tracking Platform- Component Overview + +![Component Overview](./assets/ATP_Architecture_overview.png) + +## Asset Tracking Platform- Process Flow Diagram + +![ATP Architecture](./assets/ATP_Architecture.png) + +**Components:** + +**Asset Tracking Platform (Data Provider)** + +The Asset Tracking Platform can be understood as a Hub that accepts data from IoT Networks, standardizes it, and enables it for Catena-X Components, Services, and Applications. + +**Dashboard/Application (Data Consumer)** + +A Dashboard/an Application can be used in the Catena-X Network to visualize sensor data from diverse IoT sensors. + +It enables users to search & manage assets, devices, pairs & real-time tracking of assets using geo data sensors, optimizing vendor-managed inventories through automatic filling level measurements, allowing stakeholders Tiers, customers, carriers, insurers, etc. + +**Networks**: + +The Asset Tracking Platform can be understood as a Hub that accepts data from IoT Networks, standardizes it, and enables it for Catena-X Components, Services, and Applications. + +**Business Partners**: + +These are external entities, possibly suppliers, manufacturers, carriers, or other stakeholders, who are a part of the Catena-X network. They interact with the system to exchange data related to assets. + +**EDC (Eclipse Dataspace Connector)**: + +It's the central communication component for Catena-X that acts as a bridge between different data providers and consumers within the Catena-X ecosystem to implement a framework agreement for sovereign, cross-organizational data exchange. It ensures secure and standardized data exchange. + +**dDTR (Decentralized Digital Twin registry)**: + +It's a decentralized registry that lists all digital twins and references including information about the underlying asset, asset manufacturer, and access options, like aspect endpoints. Moreover, the dDTR is used to register and find data related to DTs. + +**AAS (Asset Administration Shell) storage**: + +It acts as a database for storing standardized device and sensor data. Devices that are paired/active can send their data to the ATP for standardization. The standardized data will be appended as a Submodel to the AAS of the parent IoT Device. The ATP normalizes the sensor data received from various IoT networks, creates an AAS model, and stores it in the AAS Storage component. It is used to describe an asset electronically in a standardized manner. + +**Service discovery:** + +It has the ability to map an EDC connector endpoint to a BPN. + +**BPN Discovery Service:** + +BPN discovery services help to restrict the number of EDCs to be accessed & it maps certain information to a business partner number (BPN). It helps the business application provider to identify the BPN of the data asset under consideration. e.g. to discover available EDC connectors. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to proof, that they conform to the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +#### 1.3.1 PROOF OF CONFORMITY + +> *This section is normative* + +To proof conformity with the use case Asset Tracking: + +1. An Asset Tracking Platform as a (sensor) data provider: + + - **MUST** be able to convert the device and received network data in standardized semantic data models (IotSensorData and IotSensorDeviceDefinition). + - **MUST** register Digital Twins for IoT Sensor Devices with specific asset IDs (refer to 2.2 ADDITIONAL REQUIREMENTS) + +2. For an Asset Tracking Application as a data consumer: + + - **MUST** be able to link the digital twins of asset with one or multiple devices. + - The consumption of standardized data **MUST** be done via the EDC. + +### 1.4 EXAMPLES + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +**ATP:** +Asset Tracking Platform + +**EDC:** +Eclipse Dataspace Connector + +**dDTR:** +Decentral Digital Twin Registry + +**Business Partner Number (BPN):** +A BPN is the unique identifier of a partner within Catena-x + +**AAS:** +Asset Administration Shell + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 "Asset Tracking: Triangle Document" + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +To participate in the Asset Tracking use case, the following single standards MUST be fulfilled by all participants for which the standard is relevant: + +- CX-0002 Digital Twins in Catena-X v2.0.0 +- CX-0018 Eclipse Data Space Connector (EDC) v2.1.0 + +#### 2.1.2 DATA REQUIRED + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +The Asset Tracking Platform as a sensor data provider MUST register the Digital Twins for IoT Sensor Devices with the BPNL for ownerID, device serial number, device type, and name of manufacturer. +ex: + +```json + +{ + "description": [], + "globalAssetId": { + "value": [ + "b77383db-b9ab-48fd-ae43-d44f356d7898" + ] + }, + "idShort": "IoTDevice_123-0740-3434-A", + "identification": "b77383db-b9ab-48fd-ae43-d44f356d7898", + "specificAssetIds": [ + { + "value": "BPNL00000003ABXD", + "key": "ownerID" + }, + { + "value": "15698-0740-3434-A", + "key": "serialNumber" + }, + { + "value": "TRACK01111", + "key": "type" + }, + { + "value": "Company A", + "key": "manufacturer" + } + ], + "submodelDescriptors": [ + { + "description": [ + { + "language": "en", + "text": "The Shell for IoT Sensor Device" + } + ], + "idShort": "IotSensorDeviceDefinition", + "identification": "8c73e97a-62a9-4b29-b33a-e55cfbf5f342", + "semanticId": { + "value": [ + "urn:samm:io.catenax.iot_sensor_device_definition:2.0.0#IotSensorDeviceDefinition" + ] + }, + "endpoints": [ + { + "interface": "EDC", + "protocolInformation": { + "endpointAddress": "https://{company_edc}/edcs/19b22764-032d-4625-a9db-cbaa695e5cfa/assets/b77383db-b9ab-48fd-ae43-d44f356d7898", + "endpointProtocol": "IDS/ECLIPSE DATASPACE CONNECTOR", + "endpointProtocolVersion": "0.0.1-SNAPSHOT" + } + } + ] + } + ] +} + +``` + +## 3 ASPECT MODELS + +> *This section is normative* + +### 3.1 ASPECT MODEL "IotSensorDeviceDefinition v2.0.0" + +#### 3.1.1 INTRODUCTION + +This aspect model is needed for the onboarding process of an IoT Sensor Device for the registration in Catena-X network. The onboarding process is done via the Asset Tracking Platform (ATP). + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf). +The data model is described in SAMM and like all Catena-X data models, this model is available in a machine-readable format on GitHub2F2F conformant to CX-0003. + +#### 3.1.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group Circular Economy - Asset Tracking (CAT). This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons4F4F. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +> urn:samm:io.catenax.iot_sensor_device_definition:2.0.0 + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +The data model is described in SAMM. The generated documentation can be found here: +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.iot_sensor_device_definition/2.0.0/gen + +##### 3.1.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating +additional file formats and serializations. + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.iot_sensor_device_definition/2.0.0/IotSensorDeviceDefinition.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.iot_sensor_device_definition/2.0.0/gen/IotSensorDeviceDefinition-schema.json + +##### 3.1.5.3 AASX + +A AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf)]. + +### 3.2 ASPECT MODEL "IotSensorData v2.0.0" + +#### 3.2.1 INTRODUCTION + +The aspect model “IotSensorData” represents a set of data collected from IoT sensor devices. The sensor values are interpretable only in relation to the assets which they are attached to. + +#### 3.2.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in +accordance to the "semantic driven workflow" to create a submodel template +specification [SMT](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf). + +This aspect model is written SAMM as a modeling language and like all Catena-X data models, this model is available in a machine-readable format on GitHub2F2F +conformant to CX-0003. + +#### 3.2.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group Circular Economy - Asset Tracking (CAT). +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons4F4F. + +#### 3.2.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +> urn:samm:io.catenax.iot_sensor_data:2.0.0 + +#### 3.2.5 FORMATS OF SEMANTIC MODEL + +The data model is described in SAMM. +The generated documentation can be found here: +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.iot_sensor_data/2.0.0/gen + +##### 3.2.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating +additional file formats and serializations. + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.iot_sensor_data/2.0.0/IotSensorData.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +##### 3.2.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.iot_sensor_data/2.0.0/gen/IotSensorData-schema.json + +##### 3.2.5.3 AASX + +A AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf)]. + +### 3.3 ASPECT MODEL "AssetTrackerLinks v2.0.0" + +#### 3.3.1 INTRODUCTION + +The aspect model “AssetTrackerLinks” is used by the Asset Tracking Application to create a link between an individual asset and individual IoT sensor device. + +#### 3.3.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf). + +This aspect model is written in SAMM as a modeling language and like all Catena-X data models, this model is available in a machine-readable format on GitHub2F2F conformant to CX-0003. + +#### 3.3.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group Circular Economy - Asset Tracking (CAT). This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons4F4F. + +#### 3.3.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + + **urn:samm:io.catenax.asset_tracker_links:2.0.0** + +#### 3.3.5 FORMATS OF SEMANTIC MODEL + +The data model is described in SAMM. The generated documenattion can be found here: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.asset_tracker_links/2.0.0/gen + +##### 3.3.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.asset_tracker_links/2.0.0/AssetTrackerLinks.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.3.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.asset_tracker_links/2.0.0/gen/AssetTrackerLinks-schema.json + +##### 3.3.5.3 AASX + +A AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf). + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +> *This section is normative* + +The ATP API is logically structured in five groups: + +- API Management / Administration +- Device Management +- Network Administration +- Handling IoT Data +- Catena-X + +Each group is protected and thus can only be accessed by providing a valid API Key. + +API Management allows you to manage the ATP API. With the basic implementation it comes with creating and deleting API Keys that allows users to access the APIs resources. These endpoints are explicitly protected and only allow access if the requesting entity has the role of an administrator. When initially creating an ATP instance with a database, the +admin key must be provided via the config-file. Newly added keys will, by default, only have the "USER"-role and can therefore not create or delete any new API keys. + +The device management resources allows the management of IoT devices in their network. For example, if a user wants to +request a device information which it has in its network, the data can be requested via these endpoints. + +Network administration resources provide access to specific management functions provided by the network. + +IoT data is handled by sending the data object to a specific API endpoint. By doing so, the data will be handled +depending on the network it was sent from. It is then normalized and provided to the Catena-X network. + +Catena-X resources allow the interaction with digital twins. If an IoT device and its data shall be introduced to the +Catena-X network, the user may request the creation of a digital twin via this resource. + +## 4.1 PRECONDITIONS AND DEPENDENCIES + +In order to persist the necessary data, a persistence module, specifically a database, is REQUIRED by the ATP. In there, +the ATP stores the API Keys and Device Registry Entries that help with associating a devices network and Catena-X +information. + +Communication with an IoT network is established via HTTP requests. By doing so, users can request non-standardized data from the respective network. + +All standardized data, including the digital representation of an IoT device (Digital Twins, Shell Descriptors) and its data, is provided as a submodel via a decentral AAS. This data is accessible via an EDC. Therefore, when providing and exchanging data to the Catena-X network, an EDC is REQUIRED. The same is applicable for consuming the data, as access to the provided data is also granted via an EDC. Therefore, when consuming data from the ATP, an EDC is also REQUIRED. + +To make the data discoverable in the Catena-X network, a Shell Descriptor MUST be created. Therefore, a decentralized DTR instance is REQUIRED. + +## 4.2 API SPECIFICATION + +### 4.2.1 API ENDPOINTS & RESOURCES + +**GET LIST OF IOT DEVICES FROM IOT NETWORK** + +**GET** ``https://{baseURL}/{apiVersion}/devices/{network}`` + +**Description**: +Receive a list of devices registered in the specified network. + +**Path Parameters** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-----------------------------------------------------------------------------------------------| +| baseURL | string | Base URL | +| apiVersion | string | Version name | +| network | string | Target network the ATP shall request the data from | + +**Request Headers** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-------------------------------------------------| +| Authorization | string | Bearer Token ("Bearer \") | + +**Response Structure** + +Response if target network is Helium: + +```json +[ + { + "active": true, + "app_eui": "A000000000123456", + "app_key": "67221B144A199D9966689BDF425EEBFA", + "app_s_key": "9ECAF3A8D812345DB7F42EC9800B75EF", + "dev_eui": "A840414F11821234", + "devaddr": "48123456", + "dc_usage": 10, + "id": "fb212345-5bc9-4c43-8acc-699062cb0419", + "in_xor_filter": true, + "labels": [ + { + "id": "1f58c1c6-a4be-4c8b-920c-123f47a30e12", + "name": "Label-Name" + } + ], + "last_connected": "2022-08-24T21:01:42", + "name": "Device Name", + "nwk_s_key": "1234A97DFB42E31C592ACF369910312B", + "organization_id": "ac123b7b-6128-4af4-1234-0ea07d37182e", + "oui": 1, + "region": "EU123", + "rx_delay": 1, + "total_packets": 5 + } +] +``` + +| **Key** | **Value Type** | **Description** | +|-------------------|-------------------|-------------------| +| active | boolean | Device is active (sends data to Helium network) or not | +| app\_eui | string | LoRaWAN App EUI uniquely identifies the application of the device | +| app\_key | string | LoRaWAN App Key is a shared secret key which is used to derive secure sessions via the Join mechanism | +| app\_s\_key | string | The Application Session Key (AppSKey) is used for encryption and decryption of the payload. | +| dev_eui | string | LoRaWAN Device EUI uniquely identifies a device | +| devaddr | string | A device defined by (AppEUI, DevEUI) can be allocated to any of the DevAddrs owned by the OUI (Organizationally Unique Identifier) | +| dc_usage | number (int) | Data Credit Usage of the device | +| id | string | Identifier of the device | +| in\_xor\_filter | boolean | Allows the Helium Console backend to only process known traffic and avoid spending resources on unfamiliar packets | +| labels | string | Labels attached to the device | +| id | string | UUID of the Label | +| name | string | Name of the Label | +| last\_connected | string | Last time the device has sent data to the Console | +| name | string | Name of the device | +| nwk\_s\_key | string | Network Session Key of the device | +| organization_id | string | UUID of the organization the device is registered in | +| oui | number (int) | Organizationally Unique Identifier | +| region | string | Region the device is in | +| rx\_delay | number (int) | Delay when sending data | +| total\_packets | number (int) | Total packets the device has sent | + +**GET IOT DEVICE BY UUID FROM IOT NETWORK** + +**GET** ``https://{baseURL}/{apiVersion}/devices/{network}/{deviceId}`` + +**Description** +Request the device with the corresponding id from the specified network. + +**Path Parameters** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-----------------------------------------------------------------------------------------------| +| baseURL | string | Base URL | +| apiVersion | string | Version name | +| network | string | Target network the ATP shall request the data from | +| deviceId | string | Identifier of the device in its network | + +**Request Headers** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|--------------------------------------------------| +| network | string | name of the network (e.g. "helium") | + +**Response Structure** + +Response if target network is Helium: + +```json +{ + "active": true, + "app_eui": "A000000000123456", + "app_key": "67221B144A199D9966689BDF425EEBFA", + "app_s_key": "9ECAF3A8D812345DB7F42EC9800B75EF", + "dev_eui": "A840414F11821234", + "devaddr": "48123456", + "dc_usage": 10, + "id": "fb212345-5bc9-4c43-8acc-699062cb0419", + "in_xor_filter": true, + "labels": [ + { + "id": "1f58c1c6-a4be-4c8b-920c-123f47a30e12", + "name": "Label-Name" + } + ], + "last_connected": "2022-08-24T21:01:42", + "name": "Device Name", + "nwk_s_key": "1234A97DFB42E31C592ACF369910312B", + "organization_id": "ac123b7b-6128-4af4-1234-0ea07d37182e", + "oui": 1, + "region": "EU123", + "rx_delay": 1, + "total_packets": 5 +} +``` + +| **Key** | **Value Type** | **Description** | +|-------------------|-------------------|-------------------| +| active | boolean | Device is active (sends data to Helium network) or not | +| app\_eui | string | LoRaWAN App EUI uniquely identifies the application of the device | +| app\_key | string | LoRaWAN App Key is a shared secret key which is used to derive secure sessions via the Join mechanism | +| app\_s\_key | string | The Application Session Key (AppSKey) is used for encryption and decryption of the payload. | +| dev\_eui | string | LoRaWAN Device EUI uniquely identifies a device | +| devaddr | string | A device defined by (AppEUI, DevEUI) can be allocated to any of the DevAddrs owned by the OUI (Organizationally Unique Identifier) | +| dc\_usage | number (int) | Data Credit Usage of the device | +| id | string | Identifier of the device | +| in\_xor\_filter | boolean | Allows the Helium Console backend to only process known traffic and avoid spending resources on unfamiliar packets | +| labels | List | Labels attached to the device | +| id | string | UUID of the Label | +| name | string | Name of the Label | +| last\_connected | string | Last time the device has sent data to the Console | +| name | string | Name of the device | +| nwk\_s\_key | string | Network Session Key of the device | +| organization\_id | string | UUID of the organization the device is registered in | +| oui | number (int) | Organizationally Unique Identifier | +| region | string | Region the device is in | +| rx\_delay | number (int) | Delay when sending data | +| total\_packets | number (int) | Total packets the device has sent | + +**CREATE DIGITAL TWIN - Onboarding IoT Device (Catena-X IoT device registration)** + +**POST** ``https://{baseURL}/catenax-onboarding`` + +**Description**: +Create a Digital Twin of the devices with the specified identifier. + +In this case the identifier represents the identfier of the device which it has in its own network. + +When requesting the creation of a device, the following steps are made: + +1 - Get the neccessary information for the device from its network +2 - Create an entry in the DeviceRegistry which contains information of the device in its network and its information in the Catena-X network +3 - Create and save the submodel of the device and its data list (which is at this point empty) at the submodel server +4 - Create a Data Asset in the EDC for the device submodel and data submodel +5 - Create a Policy +6 - Creating a Contract for the device EDC Asset +7 - Creating a Contract for the device data EDC Asset + +(if registerTwin is true) + +8 - Create a Shell Descriptor/Digital Twin in the dDTR instance +9 - Create a Data Asset for the Shell Descriptor in the EDC + +Devices that shall be created as a Digital Twin must be registered in the IoT network before! + +**Request Headers** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-------------------------------------------------| +| Authorization | string | Bearer Token ("Bearer \") | +| Content-Type | string | application/json | + +**Request Body** + +```json +{ + "id": "fb212345-5bc9-4c43-8acc-699062cb0419", + "network": "helium", + "registerTwin": true, + "ownerID": "BPN0000000001" +} +``` + +| **Parameter** | **Value Type** | **Description** | +|--------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| id | string | UUID of the device in the IoT network | +| network | string | Network in which the device is registered in | +| ownerID | string | BPNL of the data owner | +| registerTwin | boolean | Boolean/Flag which indicates if the EDC data asset for the device shall be registered as a AAS Descriptor in the (d)DTR instance | + +**Response Structure** + +```json +{ + "result": "DEVICE_TWIN_CREATED", + "deviceCxId": "dff4dc9b-1234-4d25-ab66-7780c7e25730", + "deviceDataCxId": "a720e3f6-ab28-498c-1234-f860d3899326" +} +``` + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|-------------|---------------------------------------------------------------------------------------------------------------| +| result | string | Result of the onboarding task (DEVICE_TWIN_CREATED, DEVICE_TWIN_CREATION_ERROR) | +| deviceCxId | string | Identiier of the device submodel, also resembles the Catena-X Identifier (null on DEVICE_TWIN_CREATION_ERROR) | +| deviceDataCxId | string | Identifier of the device data submodel | + +**GET ACTIVE STATUS OF DEVICE IN THE IOT NETWORK** + +**GET** ``https://{baseURL}/{apiVersion}/devices/{network}/{deviceId}/active-status`` + +**Description** + +Gets the current active-status of a device in its network. This states whether the device sends data to the ATP. + +"True" does not neccessarily mean that the data is normalized! Data is only normalized if the device is paired! + +**Path Parameters** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-----------------------------------------------------------------------------------------------| +| baseURL | string | Base URL | +| apiVersion | string | Version name | +| network | string | Target network the ATP shall request the data from | +| deviceId | string | Identifier of the device in its network | + +**Request Headers** + +| **Parameter Name** | **Type** | **Decscription** | +|--------------------|------------|-------------------------------| +| Authorization | string | Bearer Token ("Bearer \") | + +**Response Structure** + +```json +{ + "active": true +} +``` + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|---------------------------------------------------------------| +| active | boolean | Device is active in the corresponding network (true/false) | + +**UPDATE ACTIVE STATUS OF DEVICE IN THE IOT NETWORK** + +**PUT** ``https://{baseURL}/{apiVersion}/devices/{network}/{deviceId}/active-status`` + +**Path Parameters** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-----------------------------------------------------------------------------------------------| +| baseURL | string | Base URL | +| apiVersion | string | Version name | + | network | string | Target network the ATP shall request the data from | +| deviceId | string | Identifier of the device in its network | + +**Description** + +Activate or deactivate the specified device in the network + +**Request Headers** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-------------------------------------------------| +| Authorization | string | Bearer Token ("Bearer \") | + +**Request Body** + +```json +{ + "active": true +} +``` + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-----------------------------------------------------------------------| +| active | boolean | Request to set a devices active status in the network (true/false) | + +**Response Structure** + +```json +{ + "active": true +} +``` + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|---------------------------------------------------------------| +| active | boolean | Active status in the network after the request (true/false) | + +#### 2.2.1.2 Network Administration + +**GET NETWORK BALANCE** + +**GET** ``https://{baseURL}/{apiVersion}/administration/balance/{network}`` + +**Description** + +Receive the available balances in a network that the ATP communicates with. As some of the networks are provided by 3rd parties they are not free of charge when using them. + +Balances of -1 reflect infinite balance, e.g. when the network does not require payments. + +**Path Parameters** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-----------------------------------------------------------------------------------------------| +| baseURL | string | Base URL | +| apiVersion | string | Version name | +| network | string | Target network the ATP shall request the data from | + +**Request Headers** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-------------------------------------------------| +| Authorization | string | Bearer Token ("Bearer \") | + +**Response Structure** + +``` json + +{ + "network": "helium", + "balance": 12345, + "userId": "fb212345-5bc9-4c43-8acc-699062cb0419", + "userName": "Company Name" +} +``` + +| **Parameter Name** | **Type** | **Decscription** | +|-----------------------|---------------|-----------------------------------------------------------| +| network | string | Requested network | +| balance | number (int) | Available balance in the network (-1 equals infinite) | +| userId | string | Identifier of the user/entity the balance belongs to | +| userName | string | Name of the user/entity the balance belongs to | + +#### 4.2.1.3 Sending and Retrieving Data + +**GET PAIRED STATUS OF AN IOT DEVICE** + +**GET** ``https://{baseURL}/{apiVersion}/paired-status/{network}/{deviceId}`` + +**Description** + +Get the current active/paired status of a device. + +Response is determined by the status in the device registry and the network. + +If the device is active AND paired in both instances, it is paired and transmitting data. + +If the device is either not active in the network or not paired in the Device Registry Entry (or both), no data will be appended to the AAS as a Submodel. + +**Path Parameters** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-----------------------------------------------------------------------------------------------| +| baseURL | string | Base URL | +| apiVersion | string | Version name | +| network | string | Target network the ATP shall request the data from | +| deviceId | string | Identifier of the device in its network | + +**Request Headers** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-------------------------------------------------| +| Authorization | string | Bearer Token ("Bearer \") | + +**Response Structure** + +```json +{ + "catenaxId": "fb212345-5bc9-4c43-8acc-699062cb0419", + "networkDeviceId": "12cb64e7-d3ec-1234-b12b-fc742fcd7210", + "network": "helium", + "pairedStatus": true +} +``` + +| **Parameter Name** | **Type** | **Decscription** | +|-----------------------|------------|------------------------------------------| +| catenaxId | string | Catena-X identifier of the devices twin | +| networkDeviceId | string | Identifier of the device in its network | +| network | string | Network the device is registered in | +| pairedStatus | boolean | Current paired status of the device | + +**UPDATE PAIRED STATUS OF AN IOT DEVICE** + +**PUT** ``https://{baseURL}/{apiVersion}/paired-status`` + +**Description** + +Set the current active/paired status of a device. + +The status is updated in the Device Registry AND the corresponding IoT network. + +If 'pairedStatus' is true, data will be standardized and appended as Submodel to the AAS of the parent device. + +If it is false, no data will be handled for the specified device. + +**Path Parameters** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|----------------------------------------------------| +| baseURL | string | Base URL | +| apiVersion | string | Version name | + +**Request Headers** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-------------------------------------------------| +| Authorization | string | Bearer Token ("Bearer \") | +| Content-Type | string | application/json | + +**Request Body** + +```json +{ + "catenaxId": "fb212345-5bc9-4c43-8acc-699062cb0419", + "networkDeviceId": "12cb64e7-d3ec-1234-b12b-fc742fcd7210", + "network": "helium", + "pairedStatus": true +} +``` + +| **Parameter Name** | **Type** | **Decscription** | +|-----------------------|------------|------------------------------------------| +| catenaxId | string | Catena-X identifier of the devices twin | +| networkDeviceId | string | Identifier of the device in its network | +| network | string | Network the device is registered in | +| pairedStatus | boolean | Target paired status of the device | + +**Response Structure** + +```json +{ + "catenaxId": "fb212345-5bc9-4c43-8acc-699062cb0419", + "networkDeviceId": "12cb64e7-d3ec-1234-b12b-fc742fcd7210", + "network": "helium", + "pairedStatus": true +} +``` + +| **Parameter Name** | **Type** | **Decscription** | +|-----------------------|------------|------------------------------------------| +| catenaxId | string | Catena-X identifier of the devices twin | +| networkDeviceId | string | Identifier of the device in its network | +| network | string | Network the device is registered in | +| pairedStatus | boolean | Current paired status of the device | + +**SEND IN DATA FOR NORMALIZATION** + +**POST** ``https://{baseURL}/{apiVersion}/data/{network}`` + +**Description** +Send data in for normalization. + +After normalization, the ATP updates the submodel at the submodel server and appends the normalized data set. + +**Path Parameters** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-----------------------------------------------------------------------------------------------| +| baseURL | string | Base URL | +| apiVersion | string | Version name | +| network | string | Target network the ATP shall request the data from | + +**Request Headers** + +| **Parameter Name** | **Type** | **Decscription** | +|----------------------|------------|-------------------------------------------------| +| Content-Type | string | application/json | +| Authorization | string | Bearer Token ("Bearer \") | + +**Request Body** + +**POST** Helium Data (example) + +```json +{ + "app_eui": "000AB5BB00001234", + "dc": { + "balance": 100, + "nonce": 3 + }, + "decoded": { + "payload": { + "Battery": 80, + "GPSFixStatus": 1, + "ReportType": 1, + "acceleration": 0.004, + "altitude": 0.001, + "commandID": 1, + "humidity": 0.006, + "inData": "MOCKED", + "latitude": 9.483179, + "longitude": 47.655401, + "pressure": 0.003, + "protocolVersion": 1, + "temperature": 0.005, + "warnings": [], + "weight": 0.002 + }, + "status": "success" + }, + "dev_eui": "000AB123C0001234", + "devaddr": "46000048", + "downlink_url": "https://console.helium.com/api/v1/down/some/path", + "fcnt": 2181, + "hotspots": [ + { + "channel": 5, + "frequency": 868.1, + "hold_time": 0, + "id": "11yfeXmWN1B6JpMnYu1234kuiTVKACk7usRD2E3znbUEsxAsf", + "lat": 12.848396253775874, + "long": 8.657601264609369, + "name": "some-random-words", + "reported_at": 1694785894279, + "rssi": -137, + "snr": -21.200000762939453, + "spreading": "SF12BW125", + "status": "success" + } + ], + "id": "b9982b7c-af85-4863-97c2-80e0b01f20a8", + "metadata": { + "adr_allowed": false, + "cf_list_enabled": false, + "multi_buy": 1, + "organization_id": "ac489b7b-6128-4af4-8bb5-0ea07d37182e", + "preferred_hotspots": [], + "rx_delay": 1, + "rx_delay_actual": 1, + "rx_delay_state": "rx_delay_established" + }, + "name": "My-IoT-Sensor-Device", + "payload": "gAIM2wYlmUNEZA==", + "payload_size": 10, + "port": 2, + "raw_packet": "QEYAAEgAhQgCkGI5dwDzzIy1NuDKM7U=", + "replay": false, + "reported_at": 1694785894279, + "type": "uplink", + "uuid": "0e2187dc-a12b-1234-bfb6-5e7db92f7b68" +} +``` + +| **Key** | **Value Type** | **Description** | +|-----------------------|-------------------|-------------------| +| app_eui | string | LoRaWAN App EUI uniquely identifies the application of the device | +| dc | object | Data Credit Usage | +| balance | string | Available balance | +| nonce | string | Data Credits used for transmission | +| decoded | object | Decoded Device Data | +| payload | object | Decoded Device Payload | +| Battery | number (int) | Current Battery Level (percentage) | +| GPSFixStatus | number (int) | Indicates the type of signal or technique being used by the GPS receiver to determine its location | +| ReportType | number (int) | Report Type | +| acceleration | number (float) | Acceleration sensor value (if available) | +| altitude | number (double) | Altitude sensor value (if available) | +| commandID | number (int) | Command Identifier | +| humidity | number (float) | Humidity sensor value (if available) | +| inData | string | Input Data | +| latitude | number (double) | Latitude sensor value | +| longitude | number (double) | Longitude sensor value | +| pressure | number (float) | Pressure sensor value (if available) | +| protocolVersion | number (int) | Version of the used protocol | +| temperature | number (float) | Temperature sensor value (if available) | +| warnings | list | Warnings | +| weight | number (float) | Weight sensor value (if available) | +| status | string | Request status of Heliums POST request | +| dev_eui | string | LoRaWAN Device EUI uniquely identifies a device | +| devaddr | string | A device defined by (AppEUI, DevEUI) can be allocated to any of the DevAddrs owned by the OUI (Organizationally Unique Identifier) | +| downlink_url | string | URL for accessing the device | +| fcnt | number (int) | LoRaWAN FCnt for uplink packets; this increments with every uplink packet and can be useful for surmising whether an uplink was missed | +| hotspots | list | Array of hotspots which received the same packet | +| channel | number (int) | Channel in which the data was received in Helium | +| frequency | number (float) | In MHz, the frequency which the packet was received upon | +| hold_time | number (int) | foo | +| id | string | A base58 encoding of the hotspot's public key; this may serve as a concise unique identifier | +| lat | number (double) | The hotspots position latitude | +| long | number (double) | The hotspots position longitude | +| name | string | A human-friendly three-word encoding of the hotspot's public key | +| reported_at | number (int) | Timestamp in milliseconds | +| rssi | number (float) | Received Signal Strength Indicator is reported by the hotspot and indicates how strong the signal device's radio signal was | +| snr | number (float) | In dB, Signal to Noise Ratio is reported by the hotspot to indicate how clear the signal was relative to environmental noise | +| spreading | string | LoRa Spreading Factor and Bandwidth used for the radio transmission | +| status | string | Status of the transmission via hotspot | +| id | string | Device Identifier | +| metadata | object | Meta Data information | +| adr_allowed | boolean | Adaptive Data Rate (ADR) is a mechanism for adapting the data rate of devices in a LoRaWAN network | +| cf_list_enabled | boolean | The Join-Accept CF List configures channels according to the LoRaWAN spec to use sub-band 2 | +| multi_buy | number (int) | The Multiple Packets feature provides the ability to pay for additional packets for redundancy and location triangulation purposes | +| organization_id | string | Organization Identifier | +| preferred_hotspots | list | List of preferred hotspots the device interacts with | +| rx_delay | number (int) | Delay time value | +| rx_delay_actual | number (int) | Actual delay time value | +| rx_delay_state | string | Indicates if the RX Delay value is established | +| name | string | Name of the device | +| payload | string | Raw payload of the device | +| payload_size | number (int) | Payload size | +| port | number (int) | Port in which the data was received in Helium | +| raw_packet | string | Raw data packet of the sensor data | +| replay | boolean | Indicates if replay is activated | +| reported_at | number (int) | Timestamp in milliseconds | +| type | string | Uplink or Downlink (Uplink = Device sent data, Downlink = Access device) | +| uuid | string | UUID of the process | + +**Response Structure** + +```text +RESPONSE: OK +``` + +### 4.2.2 AVAILABLE DATA TYPES + +The API MUST use JSON as the payload transported via HTTP. + +The following Data Types/Objects can be provided by the API (refer to the endpoints for their concrete use case): + +**NetworkBalance** + +```json +{ + "type": "object", + "properties": { + "balance": { + "type": "integer", + "format": "int32" + }, + "network": { + "type": "string" + }, + "userId": { + "type": "string" + }, + "userName": { + "type": "string" + } + } +} +``` + +**ActiveStatus** + +```json +{ + "type" : "object", + "properties" : { + "active" : { + "type" : "boolean" + } + } +} +``` + +**OnboardingInformation** + +```json +{ + "type" : "object", + "properties" : { + "identifier" : { + "type" : "string" + }, + "network" : { + "type" : "string" + }, + "ownerId" : { + "type" : "string" + }, + "registerTwin" : { + "type" : "boolean" + } + } +} +``` + +**PairingInformation** + +```json +{ + "type" : "object", + "properties" : { + "catenaxId" : { + "type" : "string" + }, + "network" : { + "type" : "string" + }, + "networkDeviceId" : { + "type" : "string" + }, + "pairedStatus" : { + "type" : "boolean" + } + } +} +``` + +> **Please note:** +These objects do not include the data you will receive when consuming data via the EDC. Please refer to the EDC +documentation and the EDC Data Asset Structure! + +### 4.2.3 EDC DATA ASSET STRUCTURE + +ATP provides the specific data objects as data assets via an EDC. + +There are two relevant data models provided as a data asset: + +**IoT Sensor Device Definition** + +```json +{ + "catenaXId" : "0e2187dc-a12b-1234-bfb6-5e7db92f7b68", + "serialNumber" : "some-1234-serial-5678-number", + "type" : "some-device-type", + "ownerID" : "BPN0000000001", + "manufacturer" : "some-manufacturer-name" +} +``` + +| **Key** | **Value Type** | **Description** | +|-----------------------|-------------------|-------------------| +| catenaXId | string | UUID of the devices digital twin | +| serialNumber | string | Serial number of the device | +| type | string | Device Type | +| ownerID | string | BPN of the device owner | +| manufacturer | string | Manufacturer of the device | + +**IoT Sensor Data** + +```json +{ + "sensorRuntimeData" : [ { + "sensorData" : [ { + "sensorValue" : 32.00, + "sensorUnit" : "unit:Celsius", + "sensorType" : "Temperature" + } ], + "sensorGeoLocation" : { + "altitude" : 280.20, + "geoDataTimestamp" : "2023-02-04T14:48:54", + "latitude" : 40.20361, + "longitude" : 11.3102 + }, + "batteryLevel" : 50.00, + "timestamp" : "2023-02-04T14:48:54", + "transmissionMethod" : "LoRaWAN" + } ], + "catenaXId" : "urn:uuid:ed85f17e-29dd-473c-9cb8-d7ad1dc44d2f" +} + +``` + +| **Key** | **Value Type** | **Description** | +|-----------------------|-------------------|-------------------| +| catenaXId | string | UUID of the devices digital twin the data was sent from | +| sensorRuntimeData | object |The information collected by a Sensor device at an instance in time. | +| sensorData |object |The data collected by an IoT Sensor Device.| +| sensorType | string | Different types of sensors that are commonly used in various applications, measuring one of the physical properties like Temperature, Pressure, Resistance, Shock, Conduction, Heat Transfer etc. | +| sensorValue | string | The measured value of the sensor type. | +| sensorUnit | string |Contains a reference to one of the units in the Unit Catalog.| +| timestamp | string | Timestamp of the sensoric values | +| sensorGeoLocation | object | Geodata, geographic data or geospatial data, refers to data and information that has explicit or implicit association with a location relative to Earth. | +| altitude | number (double) |Antenna Altitude above/below mean-sea-level (geoid). | +| latitude | number (double) | Latitude value. The angle between zenith and a plane parallel to the equator. | +| longitude | number (double) | Longitude value. Geographic coordinate that specifies the east-west position of a point on the Earth's surface. | +| geoDataTimestamp |string | geoDataTimestamp | The timestamp of the latest sensor reading of the geo data.| +| batteryLevel | integer | The battery level displays how much charge of the battery has been left. | +| transmissionMethod | string | The method under which the sensing data is transmitted from the source to the remote node. | + +### 4.2.4 ERROR HANDLING + +The API provides specific responses for successful and unsuccessful requests. + +**HttpStatusCode** + +| Code | Meaning | +|------|-----------------------| +| 200 | OK | +| 201 | Created | +| 400 | Bad Request | +| 401 | Unauthorized | +| 403 | Forbidden | +| 409 | Conflict | +| 500 | Internal Server Error | + +In case of an error, one of the following responses can occur: + +| Reason | Cause | Response Code | +|---------------------------------|-----------------------------------------------------------------------------------------------|---------------| +| Network not in path | Network parameter was not given | 400 | +| Device Identifier not in path | Device identifier parameter was not given | 400 | +| Device not found | Device was not found in its network or in the Device Registry | 400 | +| Device already onboarded | A device for which the creation of a DT was requested is already saved in the Device Registry | 409 | +| Device not paired | IoT Data for a device was received but it is not paired | 409 | +| Owner not specified | Owner was not specified in the request | 400 | +| Missing Submodel | Received IoT data but could not find a submodel to attach it to | 500 | +| Submodel Server Exception | Something went wrong while requesting something from the Submodel Server | 500 | + +## 5 REFERENCES + +### 5.1 NORMATIVE REFERENCES + +> *This section is normative* + +CX-0002 Digital Twins in Catena-X v2.0.0 + +CX-0018 Eclipse Data Space Connector (EDC) v2.1.0 + +CX-0045 Aspect Model Data Chain Template v1.1.1 + +CX-0083 Aspect Model IoTSensorDeviceDefinition v1.0.0 + +CX-0106 Aspect Model IoTSensorData v1.0.0 + +CX-0104 Aspect Model AssetTrackerLinks v1.0.0 + +CX-0070 Asset Tracking Platform API Standardization v1.0.0 + +### 5.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +### 5.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +## Onboarding Process Of IoT Sensor Devices + +![Device Onboarding](./assets/OnboardingProcessOfIoTSensorDevice.png) + +## Receive IoT Sensor Data from the network in ATP + +![Receive IoT data from Network](./assets/ReceiveIoTSensorDataFromNetworkInAtp.png) + +## Pair / Unpair IoT Device from an Asset + +![Pair / Unpair IoT Device from an Asset ](./assets/pair_unpair_device.png) + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0105-AssetTrackingUseCase/assets/ATP_Architecture.png b/docs/standards/CX-0105-AssetTrackingUseCase/assets/ATP_Architecture.png new file mode 100644 index 000000000..2920df238 Binary files /dev/null and b/docs/standards/CX-0105-AssetTrackingUseCase/assets/ATP_Architecture.png differ diff --git a/docs/standards/CX-0105-AssetTrackingUseCase/assets/ATP_Architecture_overview.png b/docs/standards/CX-0105-AssetTrackingUseCase/assets/ATP_Architecture_overview.png new file mode 100644 index 000000000..940802444 Binary files /dev/null and b/docs/standards/CX-0105-AssetTrackingUseCase/assets/ATP_Architecture_overview.png differ diff --git a/docs/standards/CX-0105-AssetTrackingUseCase/assets/OnboardingProcessOfIoTSensorDevice.png b/docs/standards/CX-0105-AssetTrackingUseCase/assets/OnboardingProcessOfIoTSensorDevice.png new file mode 100644 index 000000000..570fc6ee3 Binary files /dev/null and b/docs/standards/CX-0105-AssetTrackingUseCase/assets/OnboardingProcessOfIoTSensorDevice.png differ diff --git a/docs/standards/CX-0105-AssetTrackingUseCase/assets/ReceiveIoTSensorDataFromNetworkInAtp.png b/docs/standards/CX-0105-AssetTrackingUseCase/assets/ReceiveIoTSensorDataFromNetworkInAtp.png new file mode 100644 index 000000000..94e49bb73 Binary files /dev/null and b/docs/standards/CX-0105-AssetTrackingUseCase/assets/ReceiveIoTSensorDataFromNetworkInAtp.png differ diff --git a/docs/standards/CX-0105-AssetTrackingUseCase/assets/atp-global-architecture.png b/docs/standards/CX-0105-AssetTrackingUseCase/assets/atp-global-architecture.png new file mode 100644 index 000000000..f79dd240f Binary files /dev/null and b/docs/standards/CX-0105-AssetTrackingUseCase/assets/atp-global-architecture.png differ diff --git a/docs/standards/CX-0105-AssetTrackingUseCase/assets/atp-middleware.png b/docs/standards/CX-0105-AssetTrackingUseCase/assets/atp-middleware.png new file mode 100644 index 000000000..4cd38c275 Binary files /dev/null and b/docs/standards/CX-0105-AssetTrackingUseCase/assets/atp-middleware.png differ diff --git a/docs/standards/CX-0105-AssetTrackingUseCase/assets/pair_unpair_device.png b/docs/standards/CX-0105-AssetTrackingUseCase/assets/pair_unpair_device.png new file mode 100644 index 000000000..91dedff6d Binary files /dev/null and b/docs/standards/CX-0105-AssetTrackingUseCase/assets/pair_unpair_device.png differ diff --git a/docs/standards/CX-0115-ManufacturingCapabilityExchange/CX-0115-ManufacturingCapabilityExchange.md b/docs/standards/CX-0115-ManufacturingCapabilityExchange/CX-0115-ManufacturingCapabilityExchange.md new file mode 100644 index 000000000..2211697a7 --- /dev/null +++ b/docs/standards/CX-0115-ManufacturingCapabilityExchange/CX-0115-ManufacturingCapabilityExchange.md @@ -0,0 +1,827 @@ +# CX-0115 Manufacturing Capability Exchange 1.0.0 + +## ABSTRACT + +Manufacturing-as-a-Service (MaaS) scenarios focus on connecting buyers looking for manufacturers in +possession of the available production know-how and resources to produce specific products. + +Sharing information about the required and available manufacturing capabilities in an interoperable +manner is fundamental for any MaaS solution providing basic and value-added services such as +automated search and matchmaking. + +A common description of the manufacturing capabilities based on a standardized semantic definition +is therefore key for facilitating such an information exchange between Catena-X participants. + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +This is the first version of the CX-0115 standard. The CX-0115 standard obsoletes the following +Catena-X standards: + +- CX-0052 ManufacturingCapability Aspect Model v1.0.0 + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following roles defined in [[CX-OMW]](#62-non-normative-references): + +- **Business Application Provider** providing Manufacturing-as-a-Service solutions +- **Data Provider** willing to provide information about required or available capabilities +- **Data Consumer** interested in requesting information about required or available capabilities +- **On-Boarding Service Provider** supporting the onboarding of participants with their business and + capability information +- **Enablement Service Provider** that support the workflow regarding the derivation and refinement + of participants capabilities + +The scope of this standard is only the “ManufacturingCapability” aspect model and the provisioning of +manufacturing capabilities data in accordance with [[CX-0002]](#61-normative-references). + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +Buyers occasionally need to search for manufacturers or specific manufacturing process steps. The +reasons for that might be that production at their own premises is currently not possible due to +resource or capacity bottlenecks (e.g. material shortage, machine defect, no machine with required +capabilities available, etc.), that other suppliers are currently not able to deliver a particular +product, or that a prototype of a new product is needed before a production and investment decision +is made. Instead of searching for the right supplier based on already existing but possibly limited +contacts, Catena-X MaaS enables the distribution of a pre-configured manufacturing request across a +network of ODM platforms and supplier networks in a domain-independent and IP-secure manner. + +Buyers looking for manufacturers to purchase specific products or manufacturing process steps from, +must provide specific information on how the products should be manufactured. This includes the +required manufacturing capabilities that a manufacturer needs to possess in order to manufacture the +desired product or perform the manufacturing process steps. Manufacturers, on the other hand, are +interested in providing information about their know-how and available capabilities, making them +discoverable for potential buyers and allowing them to acquire new customers, orders and projects. + +The standardized "ManufacturingCapability" model defined in this document is a first step towards a +common interoperability of manufacturing capabilities by all participants in a Manufacturing-as-a-Service +scenario. It therefore fosters the interoperability of suppliers and buyers in the manufacturing industry, +enabling faster alignment with less effort and making collaboration less error-prone. + +Figure 1 shows the high-level architecture of the manufacturing capability exchange in the Catena-X +dataspace and the services that are involved. Both the data provider and the data consumer must be +members of the Catena-X network in order to communicate with each other. With the help of the +Credential Service and the Identity Access Management (IAM) each participant can authenticate +itself, verify the identity of the requesting party and decide whether to authorize the request. The +manufacturing capability data is provisioned in accordance with [[CX-0002]](#61-normative-references). + +![Figure 1: High-level architecture of the Manufacturing Capability exchange in Catena-X network_](./assets/Figure_1.svg) +*Figure 1: High-level architecture of the Manufacturing Capability exchange in Catena-X network* + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative_ + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples and notes +in this specification are non-normative. Everything else in this specification is normative. +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, +**SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in [BCP 14] +[[RFC2119]](#62-non-normative-references) [[RFC8174]](#62-non-normative-references) when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X +standards. To validate that the standards are applied correctly, Catena-X employs Conformity +Assessment Bodies (CABs). The proof of conformity for a single semantic model is done according to +the general rules for proving the conformity of data provided to a semantic model or the ability to +consume the corresponding data. + +### 1.4 EXAMPLES + +The following example shows a value-only JSON serialization of the Manufacturing Capability aspect +model: + +```json +{ + "machineTools" : [ { + "canProcessMaterials" : [ { + "belongsToMaterialFamilies" : [ { + "properties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "label" : { + "en" : "aluminum" + } + } ], + "properties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "label" : { + "en" : "aluminum" + } + } ], + "specializes" : [ { + "hierarchyElementId" : "123" + } ], + "generalizes" : [ { + "hierarchyElementId" : "123" + } ], + "hierarchyElementId" : "123" + } ], + "processes" : [ { + "billOfProcessIdentification" : "www.1234-bar-chair-billOfProcess.de" + } ], + "machines" : [ { + "containsTools" : [ { + "canProcessMaterials" : [ { + "belongsToMaterialFamilies" : [ { + "properties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "label" : { + "en" : "aluminum" + } + } ], + "properties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "label" : { + "en" : "aluminum" + } + } ], + "specializes" : [ { + "hierarchyElementId" : "123" + } ], + "generalizes" : [ { + "hierarchyElementId" : "123" + } ], + "hierarchyElementId" : "123" + } ], + "label" : { + "en" : "aluminum" + }, + "provides" : [ { + "specializes" : [ { + "hierarchyElementId" : "123" + } ], + "capabilityConstraintSet" : [ { + "capabilityConstraintProperties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "refersToMaterial" : { + "belongsToMaterialFamilies" : [ { + "properties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "label" : { + "en" : "aluminum" + } + } ], + "label" : { + "en" : "aluminum" + }, + "properties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "@type" : "MaterialEntity" + } + } ], + "capabilityId" : "urn:manufacturing-capability:capability:42", + "capabilityLabel" : { + "en" : "sawing" + }, + "generalizes" : [ { + "hierarchyElementId" : "123" + } ], + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "hierarchyElementId" : "123" + } ], + "properties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ] + } ], + "capabilities" : [ { + "specializes" : [ { + "hierarchyElementId" : "123" + } ], + "capabilityConstraintSet" : [ { + "capabilityConstraintProperties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "refersToMaterial" : { + "belongsToMaterialFamilies" : [ { + "properties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "label" : { + "en" : "aluminum" + } + } ], + "label" : { + "en" : "aluminum" + }, + "properties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "@type" : "MaterialEntity" + } + } ], + "capabilityId" : "urn:manufacturing-capability:capability:42", + "capabilityLabel" : { + "en" : "sawing" + }, + "generalizes" : [ { + "hierarchyElementId" : "123" + } ], + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "hierarchyElementId" : "123" + } ], + "certificates" : [ { + "properties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "label" : { + "en" : "aluminum" + } + } ], + "products" : [ { + "properties" : [ { + "semanticReferences" : [ { + "semanticReferenceId" : "urn:eclass:0173-1#02-AAF583#002" + } ], + "propertyLabel" : { + "en" : "nominal voltage" + }, + "propertyValue" : "220" + } ], + "label" : { + "en" : "aluminum" + } + } ] +} +``` + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +| Term | Description +| --- | --- +| Aspect Model | A formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect. +| Business Partner Number (BPN) | A BPN is the unique identifier of a partner within Catena-X as defined in [[CX-0010]](#61-normative-references). +| Buyer | Person (or organization) using a manufacturing service, e.g. the milling and drilling to produce a part of their own design. +| Capability | A Capability is an Entity which represents a designated function to achieve an effect in the physical or virtual world [Plattform Industrie 4.0]. Inherits relations from Entity. [[Patzer-2023]](#62-non-normative-references) +| Manufacturer | Organization providing a manufacturing service to others, such as milling or drilling. +| Manufacturing Network Registry | A system able to onboard the capabilities of manufacturers, persist them and perform manufacturing network searches. +| Resource | A (Production) Resource is a function unit needed to perform required operations. It differs from other resources such as energy or raw materials. [[Patzer-2023]](#62-non-normative-references) +| Process | A process is a set of interacting operations in a system by which matter, energy or information is transformed, transported or stored [[IEV 351-42-33]](#62-non-normative-references) A process is a set of process steps or a single process step. It may contain sub-processes. Inherits relations from Entity. [[Patzer-2023]](#62-non-normative-references) +| Product | A Product is a material good or an (immaterial) service offering which is an outcome (output product) or an input (input product) of a Process. Inherits relations from Entity and Asset. +| Property | A Property is an attribute of an Entity which might - but does not need to have – data. [[Patzer-2023]](#62-non-normative-references) +| Digital Twin | Based on CX-0002 Standard a digital twin (DT) describes a digital representation of an asset sufficient to meet the requirements of a set of use cases. For detailed information please refer to [[CX-0002]](#61-normative-references). + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 Manufacturing Capability Exchange + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +The following Catena-X standards are prerequisite for the implementation of this standard and therefore +**MUST** be considered / implemented by the relevant parties specified in each of them. + +| **Number** | **Standard** | **Version** +| --- | --- | --- +| [[CX-0001]](#61-normative-references) | EDC Discovery API | 1.0.2 +| [[CX-0002]](#61-normative-references) | Digital Twins in Catena-X | 2.2.0 +| [[CX-0003]](#61-normative-references) | SAMM Aspect Meta Model | 1.1.0 +| [[CX-0006]](#61-normative-references) | Registration and initial onboarding | 2.0.0 +| [[CX-0010]](#61-normative-references) | Business Partner Number (BPN) | 2.0.0 +| [[CX-0018]](#61-normative-references) | Dataspace Connectivity | 3.0.0 + +#### 2.1.2 DATA REQUIRED + +No additional data requirements. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### CONVENTIONS FOR USE CASE POLICY IN CONTEXT DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization +of data within the Catena-X use cases has been outlined. A set of specific policies on data offering +and data usage level detail the conditions under which data may be accessed, shared, and used, +ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data +usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository [[CX-ODRL]](#62-non-normative-references). This document provides in-depth explanations of the + terms and conditions applied to data access and utilization, ensuring that all engagement with our data + is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. + Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +###### ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for +members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, +Data Provider maintains control over its anti-trust obligations when sharing certain data. In +particular, Data Provider may apply Access Policies to restrict access to a particular data offer +for only one Participant identified by a specific business partner number. + +- Membership +- BPNL + +###### ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use +the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are +provided via the ODRL policy repository [[CX-ODRL]](#62-non-normative-references). + +##### CONFORMITY REQUIREMENTS + +The manufacturing capability data **MUST** be sent from the manufacturer to the Manufacturing Network Registry +according to the API standard described in [Chapter 4](#4-application-programming-interfaces). + +Participants that act as a Manufacturing Network Registry within Catena-X MaaS **MUST** be able to receive +manufacturing capability data. + +Companies that act as manufacturers within Catena-X MaaS **MUST** be able to send manufacturing capability +data. + +Every provider of manufacturing capability data **MUST** provide the data conformant to the semantic +model specified in [Chapter 3](#3-aspect-models). + +The unique identifier of the semantic model specified in [Chapter 3](#3-aspect-models) **MUST** be used +by the data provider to define the semantics of the data being transferred. + +This semantic model **MUST** be made available in the central Semantic Hub. + +Data consumers and data provider **MUST** comply with the license of the semantic model defined in +[Chapter 3.1.3](#313-license). + +In the Catena-X data space ManufacturingCapability data **MUST** be exchanged via a dataspace connector +conformant to [[CX-0018]](#61-normative-references) and [[CX-0002]](#61-normative-references). + +The JSON Payload of data providers **MUST** be conformant to the JSON Schema as specified in this document. + +The characteristics BPNL and BPNS **MUST** be used according to the standard [[CX-0010]](#61-normative-references). + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +The registration and provisioning of digital twins data **MUST** be done in accordance with [[CX-0002]](#61-normative-references). + +## 3 ASPECT MODELS + +> *This section is normative* + +### 3.1 ASPECT MODEL "Manufacturing Capability" + +#### 3.1.1 INTRODUCTION + +This section describes the "Manufacturing Capability" semantic model used in the Catena-X network. +For the complete semantics and detailed description of its properties refer to the SAMM model in +[Chapter 3.1.5.1](#3151-rdf-turtle). + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the +"semantic driven workflow" to create a submodel template specification [[SMT]](#62-non-normative-references). + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [[CX-0003]](#61-normative-references) as +input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to [[CX-0003]](#61-normative-references). + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + urn:samm:io.catenax.manufacturing_capability:3.1.0 +``` + +This identifier **MUST** be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The RDF turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating +additional file formats and serializations. + +> [https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.manufacturing_capability/3.1.0/ManufacturingCapability.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.manufacturing_capability/3.1.0/ManufacturingCapability.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema **MUST** be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation *"GetSubmodel"*. + +##### 3.1.5.3 AASX + +An AASX file **MUST** be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to [[SMT]](#62-non-normative-references). + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +### 4.1 "Manufacturing Capability" API + +The Manufacturing Capability API defined in this section enables the exchange of the Manufacturing Capability +data between Catena-X manufacturers and the Manufacturing Network Registry (MNR) in an interoperable +manner. The manufacturer maintains a set of Submodels (one for each plant) and registers them in their +Digital Twin Registry in accordance with [[CX-0002]](#61-normative-references). To exchange the manufacturer's manufacturing +capabilities, the manufacturer must first onboard in Catena-X MaaS. Details on the manufacturer onboarding +process can be found in the Runtime View section of the [[MaaS KIT]](#62-non-normative-references). It is assumed that the +Asset ID is known in Catena-X. Figure 2 shows a high level overview of the intended data exchange flow. + +![Figure 2: Manufacturing Capability data exchange flow](./assets/Figure_2.svg) +*Figure 2: Manufacturing Capability data exchange flow* + +The API relies on asynchronous communication between the involved parties. + +1. A data exchange is initiated by the data consumer (Manufacturing Network Registry) sending a + Pull request to the data provider (Manufacturer) to get the Manufacturing Capabilities. +2. Upon receiving a valid request, the manufacturer sends back the Manufacturing Capability Submodel so that the Manufacturing Network Registry is + able to process with the capabilities of the Manufacturing Capability Submodel. + +#### 4.1.1 PRECONDITIONS AND DEPENDENCIES + +To participate in the Catena-X dataspace, both the data consumer and the data provider **MUST** be +registered and onboarded as defined in [[CX-006]](#61-normative-references). + +A dataspace connector conformant to [[CX-0018]](#61-normative-references) **MUST** be used +to make the Manufacturing Capability API available to network participants. + +The API endpoint defined in [Chapter 4.1.2.1](#4121-api-endpoints--resources) **MUST** therefore be offered as data asset / contract +offer as defined in [[CX-0018]](#61-normative-references). + +#### 4.1.2 API SPECIFICATION + +##### 4.1.2.1 API Endpoints & Resources + +To support the exchange of Manufacturing Capability data, the Manufacturing Network Registry acting +as a data consumer **MUST** define a single endpoint supporting the HTTP GET request method as described +in [[RFC9110]](#62-non-normative-references). The structure of the endpoint **MAY** be freely chosen. The address of the endpoint +**MUST** be provided as part of the data asset structure defined in [Chapter 4.1.3](#413-connector-data-asset-structure) of this document. + +Exchanging Data via the Manufacturing Capability API requires manufacturers and the Manufacturing Network +Registry to both act in the roles of data provider and data consumer. The API is a superset of [[CX-0002]](#61-normative-references) +with the following specializations: + +- A manufacturer **MUST** host and expose a Submodel ManufacturingCapability via the Submodel-API as + defined in [[CX-0002]](#61-normative-references). +- Additionally, manufacturers and the Manufacturing Network Registry **MUST** offer the PatchSubmodel-Operation + with the content-modifier `$value` on all Submodels as defined in [[ AAS Pt.2]](#62-non-normative-references). +- A manufacturer **MUST** be capable to update the ManufacturingCapability-Submodel hosted by the + Manufacturing Network Registry. + +##### 4.1.2.2 Available Data Types + +The API **MUST** use JSON as the payload transported via HTTPS. + +#### 4.1.3 CONNECTOR DATA ASSET STRUCTURE + +Obligations for the data space connector Asset Definition of the Digital Twin Registry are inherited +from [[CX-0002]](#61-normative-references). + +Obligations for the data space connector asset definition of a Submodel are inherited from [[CX-0002]](#61-normative-references). + +Of the example below, only the `properties`- section is defined as normative. The example only signifies +a single registered Submodel. While bundling several Submodels into a single data space connector asset, +there are no normative requirements for data space connector asset properties. + +```json +{ + "@context": { + "ctx": "https://w3id.org/catenax/taxonomy#", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "aas-semantics": "https://admin-shell.io/aas/3/0/HasSemantics/" + }, + "@id": "{{ID for the data space connector asset}}", + "properties": { + "dct:type": { + "@id": "ctx:Submodel" + }, + "cx-common:version": "3.0", + "aas-semantics:semanticId": "{{urn:samm:io.catenax.manufacturing_capability:3.1.0}}" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "proxyPath": "true", + "proxyBody": "true", + "proxyMethod": "true", + "proxyQueryParams": "true", + "baseUrl": "{{Submodel endpoint ending before /submodel}}" + } +} +``` + +The API version described in this standard document **MUST** be published in the in the property +`https://w3id.org/catenax/ontology/common#version` as version `1.0` in the asset. The requester of an +asset **MUST** be able to handle multiple assets for this endpoint, being differentiated only by the +version. The requester **SHOULD** choose the asset with the highest compatible version number +implemented by themselves. If the requester cannot find a version compatible with their own, the +requester **MUST** terminate the data transfer. + +##### Connector Policy Definition + +The following policy is an example to let a single business partner pass. It could be used as (part of) +either a `accessPolicy` or a `contractPolicy`. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@type": "PolicyDefinition", + "@id": "{{POLICY-DEFINITION-ID}}", + "policy": { + "odrl:permission": [ + { + "odrl:action": "USE", + "odrl:constraint": [ + { + "odrl:leftOperand": "{{BPN attribute in Data Consumer VC}}", + "odrl:operator": "=", + "odrl:rightOperand": "{{hard-coded BPN of privileged consumer}}" + } + ] + } + ], + "odrl:prohibition": [], + "odrl:obligation": [] + } +} +``` + +##### Connector Contract Definition + +The following example for a data space connector contract definition connects the defined policy to +the defined asset. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@type": "ContractDefinition", + "@id": "contract-definition-id", + "accessPolicyId": "{{POLICY-DEFINITION-ID}}", + "contractPolicyId": "{{POLICY-DEFINITION-ID}}", + "assetsSelector": [ + { + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "{{ID for the EDC Asset}}" + } + ] +} +``` + +#### 4.1.4 ERROR HANDLING + +Error handling is specified by [[CX-0002]](#61-normative-references) and [[AAS Pt.2]](#62-non-normative-references). + +#### 4.1.5 DTR REGISTRATION + +As mandated by [[CX-0002]](#61-normative-references), all Data-Providers must provide a Digital Twin Registry (DTR) and use it +to link their Submodels to identified assets. Assets in the DTR are identified via `specificAssetIds`. + +When registering Submodels with `semanticId` `ManufacturingCapability`, the data provider (Manufacturer) +**MUST** create a single specificAssetId with key creationEntityId and value a UUIDv4 as value. + +All other attributes are standardized in [[CX-0002]](#61-normative-references) or [[AAS Pt.2]](#62-non-normative-references) respectively. + +Example: + +```json +{ + "id": "{{id of the AAS}}", + "idShort": "{{short name of the AAS}}", + "specificAssetIds": [ + { + "name": "creationEntityId", + "value": "{{someUuidV4}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "*" + } + ] + } + } + ], + "submodelDescriptors": [ + { + "id": "{{someSubmodelId}}", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.manufacturing_capability:3.1.0" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "{{dataplane baseurl extended with the appropriate path ending on /submodel}}", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id={{ID of the data space connector asset the submodel is living behind}};dspEndpoint={{controlPlaneEndpoint}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ] + } + ] +} +``` + +#### 4.1.6 DATA EXCHANGE + +Restrictions on the exchanged data can be retrieved from the data models. Additionally, the following +definitions apply. + +The ManufacturingCapability Submodel data **MUST** be sent from the manufacturer to the Manufacturing +Network Registry using an HTTP GET response. The data format described here **MUST** be followed for +the exchange of the capabilities needed for manufacturing. + +Multiple ManufacturingCapability aspects **MAY** be sent in one transfer as a JSON list. If only one +ManufacturingCapability aspect is transmitted, it **MUST** still be sent as a list with one entry. + +The serialized JSON **MUST NOT** be larger than 15 MiB in size. + +The ManufacturingCapability endpoint **MUST** be implemented by all participants who wish to participate +in Catena-X MaaS as a manufacturer. Manufacturers **MUST** be able to response with their manufacturing +capabilities to the Manufacturing Network Registry HTTP GET request. + +The data payload itself **MUST** be a valid JSON string. + +All attributes marked as mandatory in ManufacturingCapability aspect model **MUST** be included in the +dataset. Attribute marked as 'Optional' can be included in the data set. + +The usage of the attributes in the data model **MUST** follow the attribute descriptions in the definitions +of the ManufacturingCapability aspect model. + +When exchanging data, the usage of UUIDv4 is required in order to reduce the probability of +collision as well as to eliminate certain attack vectors. The UUIDv4 **MUST** be generated according to +[[RFC4122]](#62-non-normative-references). + +## 5 PROCESSES + +> *This section is normative* + +Not applicable. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normative* + +| **Number** | **Standard** | **Version** +| --- | --- | --- +| [CX-0001] | EDC Discovery API | 1.0.2 +| [CX-0002] | Digital Twins in Catena-X | 2.2.0 +| [CX-0003] | SAMM Aspect Meta Model | 1.1.0 +| [CX-0006] | Registration and initial onboarding | 2.0.0 +| [CX-0010] | Business Partner Number (BPN) | 2.0.0 +| [CX-0018] | Dataspace Connectivity | 3.0.0 + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +| **Context** | **Link** +| --- | --- +| [CX-OMW] | Catena-X Operating Model Whitepaper. Download from: [https://catena-x.net/fileadmin/\_online\_media\_/CX\_Operating\_Modelv2.1\_final.pdf](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf) +| [CX-ODRL] | Catena-X ODRL Profile repository: https://github.com/catenax-eV/cx-odrl-profile +| [RFC2119] | Bradner, S. Key words for use in RFCs to Indicate Requirement Levels. Available online: https://datatracker.ietf.org/doc/html/rfc2119 +| [RFC4122] | A Universally Unique Identifier (UUID) URN Namespace (https://www.rfc-editor.org/rfc/rfc4122) +| [RFC8174] | Leiba, B. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. Available online: https://datatracker.ietf.org/doc/html/rfc8174 +| [RFC9110] | HTTP Semantics (https://www.rfc-editor.org/rfc/rfc9110) +| [SMT] | How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf +| [IEV 351-42-33] | International Electrotechnical Commission. IEC TS 62443-1-1:2009: Industrial communication networks - Network and system security - Part 1-1: Terminology, concepts and models, 2009 (1.0). Available online: https://webstore.iec.ch/publication/7029 +| [Patzer-2023] | Patzer, F.; Schnebel, B.; Schöppenthau, F.; Watson, K. Smart Factory Web Ontology Specification: Version 1.0. Available online: https://www.smartfactoryweb.de/docs/models/SFW_Ontology_Spec_1.0.pdf +| [MaaS KIT] | Eclipse Tractus-X MaaS KIT https://eclipse-tractusx.github.io/docs-kits/category/maas-kit + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0115-ManufacturingCapabilityExchange/assets/Figure_1.svg b/docs/standards/CX-0115-ManufacturingCapabilityExchange/assets/Figure_1.svg new file mode 100644 index 000000000..b82a6119b --- /dev/null +++ b/docs/standards/CX-0115-ManufacturingCapabilityExchange/assets/Figure_1.svg @@ -0,0 +1,4 @@ + + + +
    Data Provider
    Data Provider
    Connector
    Connector
    Busines Application
    Busines App...
    Catena-X Core Service Provider
    Catena-X Core Service Provider
    IAM
    IAM
    Credential Service
    Credential S...
    Keycloak
    Keycloak
    Data Consumer
    Data Consumer
    Connector
    Connector
    Busines Application
    Busines Applicati...
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
    (8) Get Submodel
    (8) Get Su...
    (5) Query dDTR for Twin and submodel
    (5) Query dDTR for Twin and submodel
    (4) Connector Communication
      (Catalog / Contracting / Transfer)  
    (4) Connector Communication...
    dDTR
    dDTR
    Submodel Endpoint
    Submodel E...
    (10) Get Submodel
    (10) Get S...
    (3) Register Twin
    with Submodels
    (3) Register Twin...
    (2) Register Submodel Endpoint
     at Connector
    (2) Register Submodel Endpoint...
    (9)
    (9)
    Text
    Text
    (6) Get lookup/shells
    by specific asset ids
    (6) Get lookup/shells...
    (1) Register dDTR at Connector
    (1) Register dDTR at Connector
    (7) Get shell-descriptors
    by AAS ID
    (7) Get shell-descriptors...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0115-ManufacturingCapabilityExchange/assets/Figure_2.puml b/docs/standards/CX-0115-ManufacturingCapabilityExchange/assets/Figure_2.puml new file mode 100644 index 000000000..530512eec --- /dev/null +++ b/docs/standards/CX-0115-ManufacturingCapabilityExchange/assets/Figure_2.puml @@ -0,0 +1,19 @@ +@startuml Figure_2 +autonumber +skinparam sequenceMessageAlign center + + +box "Data Provider (Manufacturer)" +participant "Business\nApplication" as app_prov +end box + +box "Data Consumer (Manufacturing Network Registry)" +participant "Business\nApplication" as app_cons +end box + + + +app_cons -> app_prov: Get "Asset ID" +note right: Manufacturing Capability Endpoint +return Submodel +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0115-ManufacturingCapabilityExchange/assets/Figure_2.svg b/docs/standards/CX-0115-ManufacturingCapabilityExchange/assets/Figure_2.svg new file mode 100644 index 000000000..61662b641 --- /dev/null +++ b/docs/standards/CX-0115-ManufacturingCapabilityExchange/assets/Figure_2.svg @@ -0,0 +1,35 @@ +Data ConsumerData ProviderBusinessApplicationBusinessApplicationBusinessApplicationBusinessApplication1Request "Material Demand Exchange"Request Endpoint2Accepted3Determine requested Material Demand4Send requested Material DemandResponse Endpoint5Accepted \ No newline at end of file diff --git a/docs/standards/CX-0116-SanctionWatchlistDashboard/CX-0116-SanctionWatchlistDashboard.md b/docs/standards/CX-0116-SanctionWatchlistDashboard/CX-0116-SanctionWatchlistDashboard.md new file mode 100644 index 000000000..bea446174 --- /dev/null +++ b/docs/standards/CX-0116-SanctionWatchlistDashboard/CX-0116-SanctionWatchlistDashboard.md @@ -0,0 +1,328 @@ +# CX-0116 Sanction Party Watchlist Dashboard v1.2.0 + +## TABLE OF CONTENTS + +## ABSTRACT + +Doing business with companies (and affiliates) which are sanctioned or affected by embargos can result in fines and reputational damage. However, identification of sanctioned partners is difficult due to the vast amount of different sanction lists from several countries and authorities. Even manual checks are difficult due to a lack of high-quality data provisioned by the authorities. With Sanction and Watchlist Monitoring, data synchronized with a data mirror is monitored continuously against the latest sanction and watch lists. The Sanction Party Watchlist Dashboard (SWD) has to provide a summary on potential matches. The matching against sanction and watch lists have to be activated in the company data lookup, so data maintainers are already notified during creation or update workflows. The monitoring scope has to be extended to political exposed persons (so called PEPs). SWD has to visualize the outcome of the sanction watchlist monitoring rules via a dashboard. + +SWD uses the Gate API CX-0074:3.0, optional the Pool API CX-0012:4.0 based on the CX-0018:3.0 Dataspace Connectivity for pulling BP data records. SWD has to be a client/ server cloud application which contains a Web Client and a Cloud Server Application. +SWD has to contain a user and authorization management capability aligned with the CX Portal and Marketplace user management. SWD has to contain an API and has to be available in English and German language + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +| **Version** | **Publishing Date** | **Author** | **Description of Change** | +| ----------- | ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 1.1.0 | | SR | Added chapter 3 for SWD API. | +| 1.2.0 | 2024-03-13 | SR | Corrected 2.3 - country list, Added chapter 3.4 Data Types and 3.5 Data Attributes, Added chapter 3.6 for data sovereignty as additional requirement. | + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +*This section is non-normative.* + +This standard is relevant for the following audience: + +- Catena-X certified Operational Companies acting as: + - Core Service Provider + - Business Application Provider + - Data Provider and Consumer + +Screening and monitoring of BP data records to global, regional or country specific Sanction Party lists and regulations is not part of the Golden Record qualification process. Therefore has to offer SWD an optional incremental service of screening BP master data of an CX Member in his Inbound Persistence. SWD has to provide results and status codes which has to enable the navigation of CX Member and Golden Record related process steps. + +SWD has to be a Value Added Services Solution and has to get accessed via the CX Marketplace. + +SWD MUST rely on CX-0010 Business Partner Number Version 2.0.0 or higher. The Gate API MUST be implemented as defined in CX-0074 Version 3.0.0 or higher based on the OpenAPI 3.0.1 specification or higher. Access to the Catena-X standards is available via Catena-X's standard library at https://catena-x.net/de/standard-library. + +### 1.2 CONTEXT + +*This section is non-normative.* + +This document is focusing on the functionality of the Sanction Party Watchlist Dashboard (SWD) which has to be a screening and monitoring tool of CX Member BP data records in the Inbound Persistence based on the following capabilities: + +1. Continuously monitoring BP data records of a CX Member based on a unified rule methodology of global available sanction party watchlists + +2. Individual selection of sanction party watchlists + +3. Matching Score Weighting customization + +4. Sanction Watchlist results by BP data record, results status code and other filter functions + +5. Customizable dashboard functionalities and role and authorization management + +6. SWD API functionalities for accessing SWD results + +> Data Sovereignty: The SWD API allows to download sanction watchlist screening related quality results of related business partner data in a data sovereign way, because each Catena-X member has its own area of business partner data in BPDM, where private data (like customer / supplier relationships) is only visible to the Catena-X member. + +### 1.3 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +- [https://datatracker.ietf.org/doc/html/bcp14](https://datatracker.ietf.org/doc/html/bcp14) +- [Key words for use in RFCs to Indicate Requirement Levels](https://www.w3.org/TR/did-core/#bib-rfc2119)> +- [Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words](https://www.w3.org/TR/did-core/#bib-rfc8174) + +### 1.4 PROOF OF CONFORMITY + +*This section is non-normative.* + +All participants and their solutions will need to proove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +When implementing the API defined in this standard, proof of conformity must be provided by the following deliverables: + +- An OpenAPI specification defining the relevant resources for this standard +- Examples of a data assets + +### 1.5 TERMINOLOGY OF SANCTION WATCHLIST DASHBOARD COMPONENTS + +*This section is non-normative.* + +The main SWD rule methodologies are described below: + +**Sanction Party List Accessibility Unification** +SWD has to contain a functionality to unify the accessibility of defined Sanction Party Watchlists by defined sanction party relevant attributes into the SWD data model structure. It has to be capable to integrate sanction party data from APIs, JSON, XML, HTML and other data interface structures. + +**BP Data Model Enrichment** +SWD has to enrich the BP data model by defined and relevant sanction party watchlist data attributes and has to enable a unified and combined usage based on the BPN ID as defined in CX-0010 Business Partner Number Standard, Version 2.0.0. + +**Sanction Party Watchlist Match** +The SWD rules have to provide results which are classified into the Clear Match and Suspected Match. + +**Business Partner** +SWD has to be based on the BP data model structure as defined in CX-0010 Business Partner Number Version 2.0.0 and CX-0074 Business Partner Gate API, Version 3.0.0. + +**BP Shareholder Relation Risk Curation** +SWD can contain the capability to identify relations between sanctioned individuals +acting as beneficial owner/shareholders of Catena-X BPDM relevant Business Partner legal entities (BPNL – Business Partner Number Legal). +The related findings have to be presented via appropriate hit scores. + +**Incident Reporting** +SWD has to contain the functionality to report results via Incidents by BP data record. The appropriate results have to be visible via the Sanction Party Watchlist Dashboard or via an API. + +**Inbound Persistence** +The Inbound Persistence contains the BP data records which are send by a CX Member for +validation and screening using the Gate API as defined in CX-0074, Version 3.0.0 into SWD. + +### 1.6 OUT OF SCOPE + +The SWD product does not contain the functionality to correct and/or enrich a business partner data record. + +### 1.7 SANCTION PARTY WATCHLIST DASHBOARD + +SWD has to contain the following dashboard-based functionalities: + +1. Visualization of sanctioned or not sanctioned CX Member BP data records based on an Incident KPI and matching classification +2. Visualization of BP data records based on Identifier, sanction party list, date of incident, time, country, optional by shareholder or beneficial owner related to a BP +3. Search functionalities +4. Dashboard layout and view settings +5. Sanction Watchlist Weighting settings +6. Language setting for German and English + +The Sanction Party Watchlist Dashboard design relies on the Catena-X style guide. See details under confluence.catena-x.net/display/CORE/CX+Style+Guide + +SWD does contain an own API. + +## 2 SANCTION WATCHLIST DASHBOARD (NORMATIVE) + +The Sanction Party Watchlist Dashboard (SWD) MUST be a screening and monitoring tool of BP data records based on the following capabilities. + +SWD MUST provide the following capabilities: + +1. Continuously monitoring BP data records of a CX Member based on a unified rule methodology of global available sanction party watchlists + +2. Individual selection of sanction party watchlists + +3. Sanction Party Watchlist Matching Score Weighting customization + +4. Sanction Watchlist results by BP data record, results status code and other filter functions + +5. Customizable dashboard functionalities (language, chart type) +6. Role and authorization management + +7. Capability to identify Sanction Party Watchlist Incidents by BP legal entities (BPNL) +8. Capability optional to identify relations between sanctioned individuals acting as beneficial owners/shareholders of Business Partner legal entities (BPNL) +9. API enabling CX Member accessing SWD results + +The SWD rule set and visualization of business partner data MUST be based on the standards defined in CX-0010 Version 2.0.0 Business Partner Number, CX-0074 Version 3.0.0 Business Partner Gate API. + +### 2.1 PRECONDITIONS AND DEPENDENCIES + +To run the SWD the BP Number, Gate API SHOULD be set up: +https://github.com/eclipse-tractusx/bpdm/blob/main/README.md + +### 2.2 SWD SPECIFICATIONS + +The SWD rule set MUST use the following Business Partner data attributes: + +1. Legal Entity as defined by CX-0074 Version 3.0.0 or higher which contains the following attributes + - External ID + - BPNL - optional + - Legal Name Parts + - BP Type - optional + - Legal Address + +### 2.3 SWD USAGE OF NORMS + +The SWD the rule set MUST us the following ISO Norms: + +#### ISO 3166-1 + +SWD MUST use be capable to use all countries based on the ISO Norm 3166-1.   + +[ISO - ISO 3166 — Country Codes](https://www.iso.org/iso-3166-country-codes.html) + +#### ISO 20275 + +The SWD rule set MUST use the content of the ISO Norm 20275 to validate the correctness of legal names in long form and/or abbreviation in a transliterated form. + +### 2.4 SWD USAGE OF EXTERNAL DATA SOURCES + +The SWD rule set MUST use defined external data sources supporting the rule set as needed in screening BP data records against sanction party watchlist incidents. + +### 2.5 SWD RESULTS + +The SWD rule set MUST provide for each BP data record in the Inbound Persistence a result in the SWD Dashboard. + +### 2.6 SWD DASHBOARD + +The SWD Dashboard MUST provide the following results: + +1. Visualization of sanctioned or not sanctioned CX Member BP data record based on an Incident KPI and matching classification +2. Visualization of BP data records based on Identifier, sanction party list, date of incident, time, country, optional by shareholder or beneficial owner related to a BP +3. Search functionalities +4. Dashboard layout and view settings +5. Sanction Watchlist Weighting settings +6. Language setting for German and English + +The Sanction Party Watchlist Dashboard design MUST rely on the Catena-X style guide. + +- Open-source repository: https://github.com/eclipse-tractusx/portal-shared-components +- NPM package: https://www.npmjs.com/package/@catena-x/portal-shared-components/v/2.1.2 +- Storybook: https://eclipse-tractusx.github.io/portal-shared-components/?path=/docs/chip--docs + +## 3 SWD API + +### 3.1 API ENDPOINTS AND RESOURCES + +The resources MUST use the well-known HTTP request methods for CRU(D) operations: + +- POST MUST be used for create requests   +- PUT MUST be used for update requests   +- GET MUST be used for read requests   + +POST MAY also be used for read requests, if input is not given by parameters but rather by an HTTP body to bypass maximum URL length. PUT MAY also be used for upsert requests (create or update) if this is required. A state (active / inactive) at each entity MUST be used for a soft delete, so that the request method DELETE SHALL NOT be used. Other HTTP request methods SHALL NOT be used, including PATCH. + +Downloading data from the SDW API MUST follow a staging concept with two stages, so that consumers of the SWD API can compare what they have downloaded from the Inbound Persistence via the Gate API into the database of SWD against what kind of SWD rule result and status code was provided for each business partner data record. + +### 3.2 SANCTION PARTY WATCHLIST CONTROLLER + +The Sanction Party Watchlist Controller MUST allow to read (search / return) sanction party watchlist incidents status codes related to an External Identifier or BPN ID. It MUST have the following resources: + +|Sanction Party Watchlist Controller Resources |Description | +| :-: | :-: | +|GET/api/swd/business partner data record with sanction party watchlist incident status codes|Returns business partner data record with sanction party watchlist incident status information array| +|GET/api/swd/BP data records |Returns business partner data record by different search parameters| +|GET/api/swd/business partner data record with sanction party workflow status|Returns workflow status by business partner data record in Filtered Business Partner List| +|GET/api/swd/shareholder natural person list by Business Partner data record|Returns first and last name of business partner data record shareholders| + +### 3.3 SANCTION PARTY WATCHLIST SHARING STATE CONTROLLER + +The sharing state controller MUST allow to read sharing state entries of BP data records complemented by the Sanction Party Watchlist incident status results.  The sharing state controller MUST have the following resources: + +|Sharing State Resources |Description | +| :-: | :-: | +|GET/api/swd/sharing-state |Returns sharing states of business partner data record with incident status result filtered by External Identifier, BPN ID and type, country, city and address| + +### 3.4 **AVAILABLE DATA TYPES** + +The API **MUST** use JSON as the payload format transported via HTTP. Other formats can be added. These are then, however, **OPTIONAL**. + +### 3.5 **DATA ASSET STRUCTURE** + +The following data assets **MUST** be registered at the Core Service Provider so that the Sharing Member can negotiate an API usage contract with the Core Service Provider and access its dedicated BPDM Gate (hosted by the Core Service Provider) through these data assets[^6]: + +| **Name** | **Type** | **Version** | **Description** | +| ------------------------------------ | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| UploadAccessSWDForSharingMember | SWD | 1.0 | Grants the Sharing Member upload access to the SWD Admin function, SWD database and SWD changelog. This contains create / update SWD admin settings by Sharing Member role by SWD function, activate and deactivate the usage of external data sources via defined APIs and license keys. | +| ReadAccessSWDForSharingMember | SWD | 1.0 | Grants the Sharing Member read access of the SWD changelog. | +The OAuth2 client permissions **MUST** be configured to solely allow access to the API resources defined in the corresponding asset, checking HTTP method (read vs. full access), path, query parameters and body of the HTTP request. + +### 3.6 **ADDITIONAL REQUIREMENTS** + +#### 3.6.1 **CONVENTIONS FOR USE CASE POLICY IN CONTEXT OF DATA EXCHANGE** + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +#### 3.6.2 **ADDITIONAL DETAILS REGARDING ACCESS POLICIES** + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +#### 3.6.3 **ADDITIONAL DETAILS REGARDING USAGE POLICIES** + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [ + +### 3.7 ERROR HANDLING + +The following http response codes MUST be defined for all resources:   + +- 200 – OK   +- 400 – Bad Request +- 401 – Unauthorized +- 403 – Forbidden +- 404 – Not Found   +- 500 – Internal Server Error + +HTTP Status Code Registry MUST be adhered to in the implementation for the decision on when to use which error code: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml + +## 4 REFERENCES + +### 4.1 NON-NORMATIVE REFERENCES + +*This section is non-normative.* + +[CX-0010:2.0 Business Partner Number](https://catena-x.net/de/standard-library) + +[BPDM Catena-X Website](https://catena-x.net/en/offers-standards/bpdm) + +### 4.2 REFERENCE IMPLEMENTATIONS + +*This section is non-normative.* + +[Business Partner Pool API](https://github.com/eclipse-tractusx/bpdm/tree/main/bpdm-pool-api/src/main/kotlin/org/eclipse/tractusx/bpdm/pool/api) + +[Business Partner Gate API](https://github.com/eclipse-tractusx/bpdm/tree/main/bpdm-gate-api/src/main/kotlin/org/eclipse/tractusx/bpdm/gate/api) + +## ANNEXES + +### FIGURES + +### TABLES + +*This section is non-normative.* + +Intentionally left blank. + +[^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf +[^2]: https://catena-x.net/de/standardisierung/catena-x-einfuehren-umsetzen/standardisierung/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0117-UseCaseCircularEconomySecondaryMarketplace/CX-0117-UseCaseCircularEconomySecondaryMarketplace.md b/docs/standards/CX-0117-UseCaseCircularEconomySecondaryMarketplace/CX-0117-UseCaseCircularEconomySecondaryMarketplace.md new file mode 100644 index 000000000..59f495a58 --- /dev/null +++ b/docs/standards/CX-0117-UseCaseCircularEconomySecondaryMarketplace/CX-0117-UseCaseCircularEconomySecondaryMarketplace.md @@ -0,0 +1,348 @@ +# CX-0117 Use Case Circular Economy - Secondary Marketplace v1.0.0 + +## ABSTRACT + +This standard focuses on the Secondary Marketplace use case. This includes relevant requirements for data provider, that want to provide relevant data for a Marketplace Offer through Catena-X, data consumer, that are searching for detailed product information in Catena-X and Application developer/provider supporting the consuming data for detailed information of product in the marketplace of +battery passports. +In the first version the Marketplace just consume data for offered Batteries. Therefore the application use the BatteryPassport data model. + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +The CX-0117 Use Case Circular Economy - Secondary Marketplace v1.0.0 is a new standard which is based on the deprecated CX-0100 Triangle for Secondary Marketplace v1.0.0 standard. The data models from: + +- CX-0033 Data Model ReturnRequest (deprecated) +- CX-0034 Data Model Battery Pass (deprecated) +- CX-0035 Data Model Marketplaceoffer (deprecated) + +have been included with their newest released versions to assure consistency between standards. + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This document focuses on the Secondary Marketplace use case. This includes relevant requirements for + +- Data provider, that want to provide relevant data for a Marketplace Offer through Catena-X, +- Data consumer, that are searching for detailed product informations in Catena-X and +- Application developer/provider supporting battery passport data consumption in the markertplace. + +In the first version the Marketplace consumes data for offered Batteries. +Therefore the application uses the BatteryPassport data model. + +Note: Fulfilling a use-case standard by a data provider / consumer can be done in two ways: A) Purchase a certified app for the use-case. +In this case the data provider / consumer does not need to proof conformity again and B) Data Provisioning / Consumption without a certified app for the use-case. +In this case the data provider / consumer needs to proof conformity with all single standards listed in this document. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +A secondary marketplace is fundamental to establish a circular economy where components and materials are available and offered to the interested users creating new value chains and extending the life of the parts and the materials before becoming waste. + +The secondary marketplace is able to display additional information on the products, specifically batteries. In order to offer additional information about the battery to potential buyers, the marketplace uses the BatteryPass sub-model. This allows buyers to access real data. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +To prove conformity with the use case marketplace standard standard as a data consumer or app provider demonstrate that you + +- can find battery passports in the network associated with the product listing of said battery on the marketplace +- can distinguish the battery passport information from other submodels offered in the network +- can visualize battery passports as additional listing information for a battery listed on the marketplace + +To prove conformity with the use case Marketplace standard as data provider you MUST show that you follow the standards listed under 2.1.1 List of Standalone Standards + +To prove conformity with the use case Marketplace standard as app provider you MUST show that you follow the standards listed under 2.1.1 List of Standalone Standards + +### 1.4 EXAMPLES + +``` + No Example provided. +``` + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +Not applicable. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normantive* + +### 2.1 USE CASE CIRCULAR ECONOMY SECONDARY MARKETPLACE + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +To participate in the Circular Economy Secondary Marketplace use-case, the following single standards MUST be fulfilled by all participants for which the standard is relevant: + +- [CX-0001:1.0](https://catena-x.net/en/library) EDC Discovery API +- [CX-0002:2.2](https://catena-x.net/en/library) Digital Twins in Catena-X +- [CX-0003:1.1](https://catena-x.net/en/library) SAMM Semantic Aspect Meta Model +- [CX-0006:2.0](https://catena-x.net/en/library) Registration And Initial OnBoarding +- [CX-0013:2.0](https://catena-x.net/en/library) Identity of Member Companies +- [CX-0014:1.0](https://catena-x.net/en/library) Employees and Technical Users +- [CX-0015:1.0](https://catena-x.net/en/library) IAM & Access Control Paradigm +- [CX-0018:3.0](https://catena-x.net/en/library) Dataspace Connectivity +- [CX-0049:2.0](https://catena-x.net/en/library) DID Document Schema +- [CX-0050:2.0](https://catena-x.net/en/library) Framework Agreement Credential + +#### 2.1.2 DATA REQUIRED + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +See CX-0143:1.0 for the Discovery process and EDC policy usage for Battery Passes. + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +Not applicable. + +## 3 ASPECT MODELS + +> *This section is normative* + +As there is no exchange scenario defined yet, the *Marketplace Offer* is **RECOMMENDED** but **OPTIONAL**, since it is so far concerning the business application-internal data structure only. + +Additionally, two other aspect models could play a supporting role for secondary marketplaces. + +The Return Request aspect model **MAY** be used to flag a vehicle or product to indicate that there is a demand or a request for return. +It specifies the aspect of the recall of a vehicle part and thus provides the information whether and why a return request exists for a product. + +The Product Passport aspect model **MAY** provide reliable details on the product characteristics or lifecycle information, therefore complementing the basic Marketplace Offer information. More information on this aspect model can be found under CX-0143 in the standards library or under the following link: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.generic.digital_product_passport. + +In the following, all relevant semantic models for the secondary marketplace are listed. + +### 3.1 ASPECT MODEL "MARKETPLACE OFFER" + +#### 3.1.1 INTRODUCTION + +The Marketplace Offer is an aspect model that is complementary to the concept of a secondary marketplace. +It describes a product (e.g. a used, dismantled component) that is placed for sale onto the marketplace, with key supporting information such as quantity, quality, or price. It provides essential information for potential buyers and could be used in the future to exchange product information between multiple marketplaces. +This model can therefore be used to exchange offers between multiple marketplaces. + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic-driven workflow" to create a submodel template specification [[SMT]](#62-non-normative-references). + +This aspect model is written in SAMM 2.0.0 as a modeling language conformant to [[CX-0003]](#61-normative-references) as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to [[CX-0003]](#61-normative-references). + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +MarketPlaceOffer **v2.0.0** (mandatory) + +```text + urn:samm:io.catenax.market_place_offer:2.0.0 +``` + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. It can be found in the current version 2.0.0 in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.market_place_offer/2.0.0/MarketplaceOffer.ttl +``` + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". It can be found in the current version in the "gen" subfolder in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.market_place_offer/2.0.0/gen +``` + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. It can be found in the current version in the "gen" subfolder in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.market_place_offer/2.0.0/gen +``` + +### 3.2 ASPECT MODEL "BATTERY PASS" + +#### 3.2.1 INTRODUCTION + +The battery pass describes information collected during the lifecycle of a battery. The battery passport is implementing the requirements if the Regulation (EU) 2023/1542 of the European Parliament and of the Council of 12 July 2023 concerning batteries and waste batteries, amending Directive 2008/98/EC and Regulation (EU) 2019/1020 and repealing Directive 2006/66/EC. Additionally attributes come from the Proposal for Ecodesign for Sustainable Products Regulation (for additional information see [CX-0143](https://catena-x.net/en/standard-library)). +To use the model pieces of the Digital Product Passport model are imported by reference, reutilizing semantically identical parts of digital product passports from the generic data model. + +#### 3.2.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [CX-0003 SAMM Semantic Aspect Meta Model](https://catena-x.net/en/library). + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to [CX-0003 SAMM Semantic Aspect Meta Model](https://catena-x.net/en/library). + +#### 3.2.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. The license information is available in github. +In case of doubt the license, copyright and authors information in github overwrites the information in this specification document. + +#### 3.2.4 IDENTIFIER OF SEMANTIC MODEL + +This semantic model has the unique identifier: + +``` +urn:samm:io.catenax.battery.battery_pass:5.0.0# +``` + +#### 3.2.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the [SAMM command line interface](https://github.com/eclipse-esmf). + +##### 3.2.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. It can be found in the current version 5.0.0 in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.battery.battery_pass/5.0.0/BatteryPass.ttl +``` + +##### 3.2.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". It can be found in the current version in the "gen" subfolder in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.battery.battery_pass/5.0.0/gen +``` + +##### 3.2.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. It can be found in the current version in the "gen" subfolder in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.battery.battery_pass/5.0.0/gen +``` + +### 3.3 ASPECT MODEL "ReturnRequest" + +#### 3.3.1 INTRODUCTION + +A core problem of the circular economy is making the right decisions. These strategies include Rethink, Refuse, Reduce, Reuse, Refurbish, Redesign, Recycle, Recover and Rot. + +In particular, the end of life (EoL) decisions are challenges. In order for a circular economy to scale, however, these must be supported in a standardized way. The data model is used for this purpose. This supports the products R-Strategy Assistant & Circularity Dashboard to provide decision support for its users. In this first scope, the model should support the EoL decisions in particular. + +The data provided by the data provider allows relevant decisions to be derived. This leads to higher reuse and recycling rates, an economically +and ecologically balanced decision-making process and a scaled circular economy. + +The Return Request aspect is used to flag a vehicle or product to indicate that there is a demand or a request for return. It specifies the aspect of the recall of a vehicle part and thus provides the information whether and why a return request exists for a product. + +- urn:samm:io.catenax.return_request:2.0.0# + +#### 3.3.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [CX-0003 SAMM Semantic Aspect Meta Model](https://catena-x.net/en/library). + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to [CX-0003 SAMM Semantic Aspect Meta Model](https://catena-x.net/en/library). + +#### 3.3.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. The license information is available in github. +In case of doubt the license, copyright and authors information in github overwrites the information in this specification document. + +#### 3.3.4 IDENTIFIER OF SEMANTIC MODEL + +This semantic model has the unique identifier: + +``` +urn:samm:io.catenax.return_request:2.0.0# +``` + +#### 3.3.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the [SAMM command line interface](https://github.com/eclipse-esmf). + +##### 3.3.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. It can be found in the current version 2.0.0 in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.return_request/2.0.0/ReturnRequest.ttl +``` + +##### 3.3.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". It can be found in the current version in the "gen" subfolder in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.return_request/2.0.0/gen +``` + +##### 3.3.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. It can be found in the current version in the "gen" subfolder in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.return_request/2.0.0/gen +``` + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +Not applicable. + +## 5 PROCESSES + +> *This section is normative* + +Not applicable. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normative* + +``` + see 2.1 +``` + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +``` + No further references. +``` + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +``` + No reference implementations. +``` + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +![architecture.png](./assets/architecture.png) + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0117-UseCaseCircularEconomySecondaryMarketplace/assets/architecture.png b/docs/standards/CX-0117-UseCaseCircularEconomySecondaryMarketplace/assets/architecture.png new file mode 100644 index 000000000..b5a1f2a59 Binary files /dev/null and b/docs/standards/CX-0117-UseCaseCircularEconomySecondaryMarketplace/assets/architecture.png differ diff --git a/docs/standards/CX-0118-ActualDeliveryInformationExchange/CX-0118-ActualDeliveryInformationExchange.md b/docs/standards/CX-0118-ActualDeliveryInformationExchange/CX-0118-ActualDeliveryInformationExchange.md new file mode 100644 index 000000000..d4761633d --- /dev/null +++ b/docs/standards/CX-0118-ActualDeliveryInformationExchange/CX-0118-ActualDeliveryInformationExchange.md @@ -0,0 +1,1200 @@ +# CX-0118 Delivery Information Exchange 2.0.0 + +## ABSTRACT + +*Delivery Information* plays a crucial role in proactively tracking, managing, and assessing the +timely fulfillment of customer orders from various suppliers in order to avoid shortages and +bottlenecks. Relying on manual methods like phone calls, or email correspondence to collect this +data can introduce errors, does not include last-minute or real-time updates, and can +potentially cause shortages. + +One effective strategy to address these challenges involves the sharing of *Delivery Information* +among Catena-X business partners in an interoperable manner. Establishing a standardized semantic +definition to describe *delivery information* and a common API is a fundamental step to enable this +exchange and foster compatibility, thereby maximizing the range of solutions available for +mitigating any potential supply shortages. + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +Changes: + +- integration and usage of digital twins as defined in [[CX-0002]](#61-normative-references) Digital Twins in Catena-X +- harmonization of aspect model in accordance with [[CX-0126]](#61-normative-references) Industry Core: Part Type +- discontinuation of the proprietary API used in v1.0.0 of this standard +- grammatical, spelling and semantic improvements + +New Content: + +- added a note on the obligation of standard implementers to make aware that sensitive data is being + handled, see [[Chapter 2.1.3]](#213-additional-requirements). + +## 1 INTRODUCTION + +In a typical order-based manufacturing and delivery process, a customer places an order, and a +supplier undertakes the task of fulfilling it. *Delivery Information* encompasses two main +categories: logistics details and delivery metrics. Logistics details cover when and where products +are shipped, as well as the quantities involved. Delivery metrics differentiate between estimated +and actual departure and arrival times, e.g. for outbound deliveries from a supplier's factory and +inbound deliveries to a customer's factory. + +Monitoring and handling *Delivery Information* effectively between suppliers and customers plays a +crucial role in optimizing the delivery processes. Early detection and resolution of +delivery-related issues hinge on the continuous tracking of this information. However, relying on +manual communication methods, like phone calls or emails, introduces the risk of errors and consumes +valuable time. Existing ERP system interfaces, primarily tailored for order planning, might not +comprehensively cover the exchange of *Delivery Information*. + +To facilitate efficient exchange, it is essential to establish a standardized and semantically +defined description of *Delivery Information*. Standardizing semantics and exchange protocols +enables participants in the supply chain to share *Delivery Information* in an interoperable manner. + +The proposed model includes information about departure and arrival dates, times, locations, shipped +quantities, tracking number, and other relevant logistics-related information that helps in +coordinating and ensuring the smooth planning of product deliveries to their intended destination. +It allows businesses to better plan and execute deliveries, minimize delays, and optimize their +delivery processes, stock and production planning, avoiding shortages and increasing efficiency. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This document describes the *Delivery Information* semantic model used in the Catena-X network and +the associated API for exchanging *Delivery Information*. This standard is relevant for the +following roles defined in [[CX-OMW]](#62-non-normative-references): + +- **Data Providers** willing to provide *Delivery Information* data +- **Data Consumers** interested in requesting and receiving *Delivery Information* data +- **Business Application Providers** interested in providing solutions implementing this standard +- **Consulting Services Providers** interested in supporting companies fulfilling the standard + +The scope of this standard is only the Delivery Information aspect model and API. It describes the +exchange of Delivery Information data through a connector in accordance with [[CX-0018]](#61-normative-references). + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +In a typical item procurement process, a customer initiates an order, and a supplier undertakes the +task of fulfilling it. As part of this process, the *Delivery Information* typically refers to data +or details regarding when, where and in which quantities of products or goods are shipped or are +expected to be shipped. It includes information about estimated and actual delivery dates, times, +locations, shipped quantities, and other relevant logistics-related information that helps in +coordinating and ensuring the smooth delivery planning of product deliveries to their intended +destination. + +Within the framework of the Catena-X network, this standard defines the *DeliveryInformation* +aspect model. Its purpose is to establish a consistent and uniform interpretation and handling of +*Delivery Information* among all interested parties, ensuring that this data is understood and +managed in the same manner by all stakeholders. + +*Figure 1* shows the high-level architecture of the *Delivery Information* exchange in the Catena-X +dataspace and the services that are involved. Both the data provider and the data consumer +must be members of the Catena-X network in order to communicate with each other. With the help of the +Credential Service and the Identity Access Management (IAM) each participant can authenticate itself, +verify the identity of the requesting party and decide whether to authorize the request. The +*Delivery Information* data is provisioned in accordance with [[CX-0002]](#61-normative-references). + +![Figure 1: High-level architecture of the Delivery Information exchange in the Catena-X network](./assets/Figure_1.svg) +*Figure 1: High-level architecture of the Delivery Information exchange in the Catena-X network* + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. The key +words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and +**SHOULD NOT** in this document are to be interpreted as described in [[BCP 14]](#62-non-normative-references) [[RFC2119]](#62-non-normative-references) +[[RFC8174]](#62-non-normative-references) when, and only when, they appear in all capitals, as shown here. All participants and +their solutions will need to prove, that they are conform with the Catena-X standards. + +All participants and their solutions will need to prove, that they are conform with the Catena-X +standards. To validate that the standards are applied correctly, Catena-X employs Conformity +Assessment Bodies (CABs). The proof of conformity for a single semantic model is done according to +the general rules for proving the conformity of data provided to a semantic model or the ability to +consume the corresponding data. Furthermore, participants agree to follow the normative language of +this standardization document and to implement the required API-Endpoints described in [Chapter 4](#4-application-programming-interfaces). + +### 1.4 EXAMPLES + +The JSONs snippets below provide an example of the value-only serialization of the *"DeliveryInformation"* +aspect model for three different delivery situations: + +1. A not yet departed delivery - estimated departure and arrival dates +2. A delivery in transit - actual departure and estimated arrival dates +3. A delivery with actual arrival times- actual departure and arrival dates + +>**Note:** Delivery values are located in the `transitEvents` of the delivery. + +1\. The order has not yet departed from its origin, as indicated by the estimated values for both departure and arrival. This is an example of estimated delivery. + +```json +{ + "materialGlobalAssetId" : "urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df", + "positions" : [ { + "orderPositionReference" : { + "supplierOrderId" : "M-Nbr-4711", + "customerOrderId" : "C-Nbr-4711", + "customerOrderPositionId" : "PositionId-01" + }, + "deliveries" : [ { + "lastUpdatedOnDateTime" : "2023-04-28T14:23:00.123456+14:00", + "deliveryQuantity" : { + "value" : 20.0, + "unit" : "unit:piece" + }, + "transitEvents" : [ { + "dateTimeOfEvent": "2023-04-01T14:23:00+01:00", + "eventType": "estimated-departure" + }, + { + "dateTimeOfEvent": "2023-04-05T14:23:00+01:00", + "eventType": "estimated-arrival" + } ], + "trackingNumber" : "1Z9829WDE02128", + "incoterm" : "EXW", + "transitLocations" : { + "destination" : { + "bpnsProperty" : "BPNS0123456789ZZ", + "bpnaProperty" : "BPNA0123456789ZZ" + }, + "origin" : { + "bpnsProperty" : "BPNS0987654321YY", + "bpnaProperty" : "BPNA0987654321YY" + } + } + } ] + } ] +} +``` + +2\. The status of this delivery is currently in transit, denoted by the actual departure and estimated arrival values. + +```json +{ + "materialGlobalAssetId" : "urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df", + "positions" : [ { + "orderPositionReference" : { + "supplierOrderId" : "M-Nbr-4711", + "customerOrderId" : "C-Nbr-4711", + "customerOrderPositionId" : "PositionId-01" + }, + "deliveries" : [ { + "lastUpdatedOnDateTime" : "2023-04-28T14:23:00.123456+14:00", + "deliveryQuantity" : { + "value" : 20.0, + "unit" : "unit:piece" + }, + "transitEvents" : [ { + "dateTimeOfEvent": "2023-04-01T14:23:00+01:00", + "eventType": "actual-departure" + }, + { + "dateTimeOfEvent": "2023-04-05T14:23:00+01:00", + "eventType": "estimated-arrival" + } ], + "trackingNumber" : "1Z9829WDE02128", + "incoterm" : "EXW", + "transitLocations" : { + "destination" : { + "bpnsProperty" : "BPNS0123456789ZZ", + "bpnaProperty" : "BPNA0123456789ZZ" + }, + "origin" : { + "bpnsProperty" : "BPNS0123456789ZZ", + "bpnaProperty" : "BPNA0123456789ZZ" + } + } + } ] + } ] +} +``` + +3\. As seen from the actual departure and actual arrival values, this is an example of a completed delivery. + +```json +{ + "materialGlobalAssetId" : "urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df", + "positions" : [ { + "orderPositionReference" : { + "supplierOrderId" : "M-Nbr-4711", + "customerOrderId" : "C-Nbr-4711", + "customerOrderPositionId" : "PositionId-01" + }, + "deliveries" : [ { + "lastUpdatedOnDateTime" : "2023-04-28T14:23:00.123456+14:00", + "deliveryQuantity" : { + "value" : 20.0, + "unit" : "unit:piece" + }, + "transitEvents" : [ { + "dateTimeOfEvent": "2023-04-01T14:23:00+01:00", + "eventType": "actual-departure" + }, + { + "dateTimeOfEvent": "2023-04-05T14:23:00+01:00", + "eventType": "actual-arrival" + } ], + "trackingNumber" : "1Z9829WDE02128", + "incoterm" : "EXW", + "transitLocations" : { + "destination" : { + "bpnsProperty" : "BPNS0123456789ZZ", + "bpnaProperty" : "BPNA0123456789ZZ" + }, + "origin" : { + "bpnsProperty" : "BPNS0123456789ZZ", + "bpnaProperty" : "BPNA0123456789ZZ" + } + } + } ] + } ] +} +``` + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +*The following terms are especially relevant for the understanding of the standard:* + +| **Name** | **Abrev.** | **Description** | +| --- | --- | --- | +| **Incoterms** | - | Is a combination of "International" and "Commercial Terms." Incoterms are a set of standardized international trade terms that facilitate and define the responsibilities of customers and suppliers in transactions. | +| **Actual time** | - | Refers to the specific, real-time date and time when an event occurs during delivery. | +| **Estimated time** | - | Refers to a projected or estimated time for an event or occurrence, based on calculations or predictions, rather than the exact, confirmed time. | +| **Origin** | - | Is the starting point from which goods are dispatched or shipped to. | +| **Destination** | - | Is the final location where the goods are to be delivered or received. | +| **Delivery Informatio**n | - | Provides an overview of related shipments, tracking the movement of goods and associated order details, not the physical shipment. It may represent a full shipment or a portion, like a container with varied commodities. | +| **Customer** | - | The recipient of products ordered from / manufactured by a supplier. | +| **Supplier** | - | The supplier / manufacturer of a product. | +| **Identity Access Management** | IAM | IAM is a security system that regulates who can access an organization's information and systems, ensuring only authorized individuals have the right level of access to prevent unauthorized entry and protect against security risks. | +| **Digital Twin** | DT | Digital representation of an asset that provides data on aspects of the represented data following [[CX-0002]](#61-normative-references). | +| **decentralized Digital Twin Registry** | dDTR | Component providing registration and discovery API implementations following [[CX-0002]](#61-normative-references). Sometimes referred to without the "decentralized" BUT in Catena-X those are always decentralized. | +| **Asset Administration Shell** | AAS | Technical concept for Digital Twins consisting of different standards. Application in Catena-X is described in Digital Twins in Catena-X standard [[CX-0002]](#61-normative-references) | +| **Shell Descriptor** | | Technical concept of the AAS API describing metadata of an Asset Administration Shell representing a Digital Twin. It holds several identification information and metainformation about which submodels are available and where to get the data from (see [[CX-0002]](#61-normative-references), [IDTA-01002-3-0](#62-non-normative-references)). There may exist multiple Shell Descriptor for the same represented Asset (see [[CX-0126]](#61-normative-references)). | +| **Submodel Descriptor** | | Technical concept of the AAS API describing metadata of Submodels within a Shell Descriptor (Asset Administration Shell) (see [[CX-0002]](#61-normative-references), [IDTA-01002-3-0](#62-non-normative-references)). | +| **Specific Asset Ids** | | Identifiers of the Shell Descriptor (Asset Administration Shell) that refer to common identification data for an asset/material at hand e.g., manufacturer part Id. Common specific asset IDs used for identification are described in Industry Core Part Type Standard (see [[CX-0126]](#61-normative-references)). | +| **Asset Administration Shell Identifier** | AAS ID | Also referred to as Shell Descriptor id, is the technical identifier of the Shell Descriptor. | +| **Global Asset Id** | | Also referred to as Catena-X Id, is the Catena-X identifier for assets represented by Digital Twins (see [[CX-0126]](#61-normative-references)). | +| **Aspect** | | A domain-specific view on information and functionality associated with a specific Digital Twin with a reference to a concrete Aspect Model (see [[CX-0002]](#61-normative-references)). Within Catena-X, an aspect is formally described using the Semantic Aspect Meta Model (see [[CX-0003]](#61-normative-references)). | +| **Semantic Id** | | Identifier including namespace to specify the semantic description of submodels using the Semantic Aspect Meta Model (SAMM). It allows partners to know the exact data format and semantics when e.g., browsing catalogs (see [[CX-0003]](#61-normative-references)). | +| **Data Space Protocol** | DSP | A set of specifications designed to facilitate interoperable data sharing between entities governed by usage control and based on Web technologies. These specifications define the schemas and protocols required for entities to publish data, negotiate Agreements, and access data as part of a Dataspace. It is governed by the International Data Spaces Association. Connectors compliant to [[CX-0018]](#61-normative-references) support the Data Space Protocol. | +| **Shared Asset Approach** | | Digital twin pattern in which each party has a twin for the same asset (Part Type). They share the same identification data in terms of specific asset IDs and global asset ID. The digital twins do have different technical identifiers. | + +*Table 1: List of terminology helpful for understanding the standard* + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 Delivery Information + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +The following Catena-X standards are prerequisites for the implementation of this standard and therefore +**MUST** be considered / implemented by the relevant parties specified in each of them. + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0001]](#61-normative-references) | EDC Discovery API | 1.0.2 | +| [[CX-0002]](#61-normative-references) | Digital Twins in Catena-X | 2.2.0 | +| [[CX-0003]](#61-normative-references) | SAMM Aspect Meta Model | 1.1.0 | +| [[CX-0006]](#61-normative-references) | Registration and initial onboarding | 2.0.0 | +| [[CX-0010]](#61-normative-references) | Business Partner Number (BPN) | 2.0.0 | +| [[CX-0018]](#61-normative-references) | Dataspace Connectivity | 3.0.0 | +| [[CX-0126]](#61-normative-references) | Industry Core Part Type | 2.0.0 | + +*Table 2: List of mandatory standards* + +The usage of this standard may be complemented with the following Catena-X standards to further extend +the range of shortage prevention possibilities: + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0120]](#61-normative-references) | Short Term Material Demand Exchange | 2.0.0 | +| [[CX-0121]](#61-normative-references) | Planned Production Output Exchange | 2.0.0 | +| [[CX-0122]](#61-normative-references) | Item Stock Exchange | 2.0.0 | +| [[CX-0145]](#61-normative-references) | Days of Supply Exchange | 1.0.0 | +| [[CX-0146]](#61-normative-references) | Supply Chain Disruption Notifications | 1.0.0 | + +*Table 3: List of non-mandatory complementary standards* + +#### 2.1.2 DATA REQUIRED + +No additional data requirements. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### CONVENTIONS FOR USE CASE POLICY IN CONTEXT DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization +of data within the Catena-X use cases has been outlined. A set of specific policies on data offering +and data usage level detail the conditions under which data may be accessed, shared, and used, +ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data +usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository [[CX-ODRL]](#62-non-normative-references). This document provides in-depth explanations of the + terms and conditions applied to data access and utilization, ensuring that all engagement with our data + is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. + Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +###### ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for +members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, +Data Provider maintains control over its anti-trust obligations when sharing certain data. In +particular, Data Provider may apply Access Policies to restrict access to a particular data offer +for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +###### ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use +the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are +provided via the ODRL policy repository [[CX-ODRL]](#62-non-normative-references). + +##### REMINDER OF ANTITRUST + +Notice and/or acknowledgement concepts to raise awareness of antitrust issues during use of this standard +are **RECOMMENDED**, for example through the implementation of a helpdesk or pop-up info. + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +This standard builds upon the Industry Core Part Type [[CX-0126]](#61-normative-references) and the Digital Twins in +Catena-X [[CX-0002]](#61-normative-references) standards. It follows the following design patterns: + +- Usage of Digital Twins as shared assets to follow a pull approach for data. +- Usage of the specific asset IDs and further identification data for the Digital Twin for the Part Type + (see [[CX-0126]](#61-normative-references)). +- Provisioning of the *PartTypeInformation* on supplier side (see [[CX-0126]](#61-normative-references)). + +Because both parties may provide data regarding different aspects of the same Part Type Twin, they need +to use the same identification data to pinpoint it. + +- The supplier of the part has a Digital Twin representation and is then able to offer *Delivery Information* + data to customers. +- The customer, who orders or uses the part, has a Digital Twin representation to offer *Delivery Information* + data to a supplier. +- Both twins refer to the same asset and provide complementary information. They share the same identification + data in two partners' context. + - The supplier + - **MUST** create the Digital Twin first. + - **MUST** generate the Catena-X ID and ensure that the customer-specific asset IDs and submodel + descriptors are only accessible by the specific customer. + - **MAY** use the Digital Twin for multiple customers. + - The customer + - **MUST** create one Digital Twin per supplier. + - **MUST** use the Catena-X ID generated by the supplier. + +The definition of identification data (Catena-X ID, Asset Administration Shell ID, specific asset ID) +**MUST** follow the Industry Core Part Type [[CX-0126]](#61-normative-references). Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for further details. + +> ***Note:*** The Part Type Twin's data is considered sensitive. Data providers **MUST** implement appropriate +measures ensuring that competitors-specific asset IDs and/or information about submodels is accessible +only to the data consumers it concerns, but not to their competitors. + +Figure 2 shows how the shared asset approach is realized. The orange lines show which submodels belong +to the respective AAS. All *Delivery Information* specific submodels are bound to the specific +Part Type's context e.g., meaning that the *Delivery Information* aspect is described for the specific +catalog item on supplier and customer side represented by the AASs. The orange submodels are the +submodels used within this standard's context. The grey submodels are used within the Industry Core +[[CX-0126]](#61-normative-references)(*PartTypeInformation, SingleLevelBomAsPlanned, SingleLevelUsageAsPlanned*). +The blue dashed lines show the references between DTs based on Catena-X UUIDs and BPNL information that +may be resolved by the Item Relationship Service (see [[CX-0126]](#61-normative-references)). + +![Figure 2: Conceptual levels of provisioning digital twins in the shared asset approach.](./assets/Figure_2.svg) +*Figure 2: Conceptual levels of provisioning digital twins in the shared asset approach.* + +Figure 2 details two conceptual levels: + +- The Asset level contains the asset (Industry Core Part Type) represented by a Digital Twin. + The latter is provisioned as an Asset Administration Shell (AAS) within the decentralized Digital + Twin Registry (dDTR) of the data provider (supplier or customer). +- The Submodel level represents the actual information that are held by a Digital Twin (DT). Those + submodels follow the respective definition of the Semantic Aspect Meta Model (SAMM) format + (see [Chapter 3](#3-aspect-models)). The dDTR only holds meta information about the Submodel + (e.g. kind of submodel via semantic ID or connector endpoint information). + +>**Note:** Delivery information can be conveyed in both directions from Supplier to Customer and Customer to Supplier. + +## 3 ASPECT MODELS + +> *This section is normative* + +### 3.1 ASPECT MODEL "DELIVERY INFORMATION" + +#### 3.1.1 INTRODUCTION + +The *Delivery Information* semantic model defines the data and details regarding when and how +products or goods are scheduled to be delivered and actually delivered from one location to another. +It includes information about order positions, material numbers and deliveries (quantity, status of +the delivery and location of the delivery). It may include tracking number and incoterms as well. +For the complete semantics and detailed description of its properties refer to the SAMM model in +[Chapter 3.1.5.1](#3151-rdf-turtle). + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the +"semantic driven workflow" to create a submodel template specification [[SMT]](#62-non-normative-references). + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [[CX-0003]](#61-normative-references) +as input for the semantic-driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to [[CX-0003]](#61-normative-references). + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +`urn:samm:io.catenax.delivery_information:2.0.0` + +This identifier **MUST** be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The RDF turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating +additional file formats and serializations. It can be found under the following link: + +>[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.delivery_information/2.0.0/DeliveryInformation.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.delivery_information/2.0.0/DeliveryInformation.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload +of the Asset Administration Shell for the API operation *"GetSubmodel"*. + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to [[SMT]](#62-non-normative-references). + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +### 4.1 API USED TO EXCHANGE "DELIVERY INFORMATION" + +As described in [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids) this standard builds upon the [[CX-0002]](#61-normative-references) Digital Twins in Catena-X and +[[CX-0126]](#61-normative-references) Industry Core Part Type standards. Therefore, the APIs provided +by the Digital Twin standard are combined with the part identification defined in the Industry Core +standard. This chapter defines how the aforementioned standards and the [[CX-0018]](#61-normative-references) standard +**MUST** be used to facilitate the provisioning of *Delivery Information* data. The usage of the +Discovery Services defined in [[CX-0001]](#61-normative-references), [[CX-0053]](#61-normative-references) is not mandatory, +because this standard assumes an already existing business relationship between the involved parties. + +The sequence diagram in *Figure 3* provides an overview of the interactions required to register the +Part Type Twin following the shared asset approach. + +- Steps 1 & 2: Register the dDTR access for the partner at the connector +- Steps 3 & 4: When using the repository pattern, create the submodel (and twin) +- Steps 5 & 6: Register the submodel endpoint for the partner at the connector +- Steps 7 & 8: Register or update the twin Shell Descriptor relying on the registered Connector asset + for the submodel endpoint and the identification data of the partners. + +> ***Note:*** This sequence diagram is simplified and does not cover the generation of the Part Type Twin +on supplier side and the handling of the identification data needed. Both partners need to create a +Part Type Twin of the shared asset as well as provide Delivery Information data. + +![Figure 3: Flow to create and register a digital twin](./assets/Figure_3.svg) +*Figure 3: Flow to create and register a digital twin* + +The sequence diagram in Figure 4 provides an overview of the interactions required when a customer +(acting as data provider) provisions *Delivery Information* data to a supplier (acting as data consumer). + +The flow "*Supplier reads (updated) Submodel from Customer*" visualizes the sequence of calls when consuming data: + +- Steps 3 - 8: Contract dDTR usage in the connector. +- Steps 9 - 12: Lookup the Industry Core Part Type Twin for a Part Type based on the common identification data. +- Steps 13 - 18: Read the Shell Descriptor of the Industry Core Part Type Twin to extract the *Delivery Information* submodel endpoint (registered at the connector). +- Steps 19 - 24: Contract the *Delivery Information* data usage in the connector. +- Steps 25 - 29: Consume and use the *Delivery Information* data. + +![Figure 4: Flow to search a digital twin and get a submodel.](./assets/Figure_4.svg) +*Figure 4: Flow to lookup a digital twin and get a submodel.* + +> ***Note:*** Depending on the use of repository patterns and the design of the Digital Twins, the data +may be updated manually in the Submodel endpoint. + +#### 4.1.1 CONNECTOR DATA ASSET STRUCTURE + +The endpoints for the dDTR and the Submodel Endpoint **MUST** be made available BUT they **MUST NOT** +be directly called data consumer. Rather, for access to dDTRs and Submodels, there **MUST** be contracts +negotiated in accordance with the DSP. Therefore, the endpoints **MUST** be offered as connector data +assets. To make these assets easily identifiable in the connector's catalog, each asset **MUST** be +configured with a set of properties as described in the corresponding sections below. + +The following table provides an overview of the connector data assets that the parties **MUST** offer +to be able to provision and/or consume *Delivery Information* data. + +| **Party** | **REQUIRED** | **Asset** | **Purpose** | +| --- | --- | --- | --- | +| Provider | Yes | "Digital Twin Registry" | Allows a consumer to query for Part Type Twins and their *Delivery Information* submodels. | +| Provider | Yes | "Submodel Delivery Information" | Allows a consumer to read actual *Delivery Information* data related to a Part Type Twin. | +| Consumer | Yes | "Digital Twin Registry" | Allows a consumer to query for Part Type Twins and their *Delivery Information* submodels. | +| Consumer | Yes | "Submodel Delivery Information" | Allows a consumer to read actual *Delivery Information* data related to a Part Type Twin. | + +*Table 4: Connector data assets* + +In the sections below the asset definitions of the two different kinds of assets are defined. + +**Connector Data Asset Structure for "Digital Twin Registry"** + +To allow partners to find the "Delivery Information" data for a specific Industry Core Part Type Twin, +the provider **MUST** register a connector data asset (see details in [[CX-0018]](#61-normative-references)) specifying the address +of the Digital Twin Registry of the provider (see [[CX-0002]](#61-normative-references)). + +The data asset **MUST** be configured with the set of properties as defined in the table below. + +| **Object** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***@id*** | Identifier of the asset | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. | +| properties | [**http://purl.org/dc/terms/type**](http://purl.org/dc/terms/type) | Defines the "Digital Twin Registry" according to the Catena-X taxonomy. | **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#DigitalTwinRegistry"}` to allow filtering the data assets catalog for the respective "Digital Twin Registry". | +| properties | [**https://w3id.org/catenax/ontology/common#version**](https://w3id.org/catenax/ontology/common#version) | The version of the standard defining the implemented API of the "Digital Twin Registry" | **MUST** correspond to the version of the standard defining the Interfaces of the "Digital Twin Registry". The value **MUST** be set to `"3.0"` for "Digital Twin Registries" used by this standard. | +| dataAddress | **@type** | Type of the DataAddress node. | **MUST** be set to `"DataAddress"`. | +| dataAddress | ***baseUrl*** | Defines the HTTPS endpoint of the corresponding "Digital Twin Registry Endpoint". | The `{{ DIGITAL_TWIN_REGISTRY_ENDPOINT }}` refers to an URL under which the API of the "Digital Twin Registry" endpoint is available. HTTPS transport protocol **MUST** be used. | +| dataAddress | ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body | **SHOULD** be set to `"false"` to not allow the API endpoint to receive a HTTPS body via the HTTPS request. | +| dataAddress | ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method | **SHOULD** be set to `"false"` to only allow the API endpoint to receive GET requests. | +| dataAddress | ***proxyPath*** | Defines whether the endpoint allows to proxy paths for the URL | **MUST** be set to `"true"` to allow the API endpoint to receive appended paths of the HTTPS request. | +| dataAddress | ***type*** | Defines the type of data plane extension handling the data exchange | **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. | + +*Table 5: Connector data assets request properties* + +Additionally security identification information **MAY** be added to secure the "Decentralized Digital Twin Registry". + +When searching the Catalog of a provider, a consumer **SHOULD** use the following properties AND +their values to identify the Data Asset specifying "Digital Twin Registry". In the connector Data Asset +descriptions the API version valid for this standard is mentioned for the property +[`https://w3id.org/catenax/ontology/common#version`](https://w3id.org/catenax/ontology/common#version). The requester of a Data Asset **MUST** be +able to handle multiple Data Asset for this endpoint, being differentiated only by the version. +The requester **SHOULD** choose the Data Asset set with the highest compatible version number implemented +by themselves. If the requester cannot find a compatible version with their own, the requester **MUST** +terminate the data transfer. + +| **Property** | **Value** | +| --- | --- | +| http://purl.org/dc/terms/type | `{"@id": "https://w3id.org/catenax/taxonomy#DigitalTwinRegistry"}` | + +*Table 6: Connector data assets request properties values.* + +An example connector data asset definition is given below. + +>**Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "http://purl.org/dc/terms/" + }, + "@id": "{{CONNECTOR_ASSET_ID}}", + "properties": { + "dct:type": {"@id": "cx-taxo:DigitalTwinRegistry"}, + "cx-common:version": "3.0" + }, + "privateProperties": { + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ DIGITAL_TWIN_REGISTRY_ENDPOINT }}", + "proxyQueryParams": "true", + "proxyBody": "false", + "proxyPath": "true", + "proxyMethod": "false", + } +} +``` + +**Connector Data Asset Structure for "Submodel"** + +To allow partners to receive the actual "Delivery Information" data as defined in [Chapter 3](#3-aspect-models), +the provider **MUST** register a connector data asset (see details in[[ CX-0018]](#61-normative-references)) specifying the +address of the submodel endpoint (see [[CX-0002]](#61-normative-references)) providing the actual data. + +The data asset **MUST** be configured with the set of properties as defined in the table below. + +| **Object** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***@id*** | Identifier of the asset | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. | +| properties | [**http://purl.org/dc/terms/type**](https://purl.org/dc/terms/type) | Defines the "Submodel API" according to the Catena-X taxonomy. | **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#Submodel"}` to allow filtering the data assets catalog for the respective "Submodel API". | +| properties | [**https://admin-shell.io/aas/3/0/HasSemantics/semanticId**](https://admin-shell.io/aas/3/0/HasSemantics/semanticId) | The semantic identifier of the "Delivery Information" SAMM. | **MUST** be set to `{"@id": "urn:samm:io.catenax.delivery_information:2.0.0#DeliveryInformation"}` to externally define how the Submodel must be interpreted. **MUST NOT** be set, if different submodels may be returned by this API. | +| properties | [**https://w3id.org/catenax/ontology/common#**](https://w3id.org/catenax/ontology/common) **version** | Version of the Submodel Interface Specification | **MUST** be set to `"3.0"` in accordance to the Digital Twin in Catena-X Standards ([[CX-0002]](#61-normative-references)). | +| dataAddress | **@type** | Type of the DataAddress node. | **MUST** be set to "DataAddress". | +| dataAddress | ***baseUrl*** | Defines the HTTPS Submodel endpoint provisioning the *Delivery Information* data | The `{{ SUBMODEL_ENDPOINT }}` refers to an URL under which the Submodel API Endpoint ([[CX-0002]](#61-normative-references)) is available to provide the "Delivery Information" . HTTPS transport protocol **MUST** be used. | +| dataAddress | ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body | **SHOULD** be set to `"false"` to not allow the API endpoint to receive a HTTPS body via the HTTPS request. | +| dataAddress | ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method | **SHOULD** be set to `"false"` to only allow the API endpoint to receive GET requests. | +| dataAddress | ***proxyPath*** | Defines whether the endpoint allows to proxy paths for the URL | **MUST** be set to `"true"` to allow the API endpoint to receive appended paths of the HTTPS request. Setting this parameter depends on the implementation of the submodel lookup. | +| dataAddress | ***type*** | Defines the type of data plane extension handling the data exchange | **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. | + +*Table 7: Connector data assets request properties* + +Additionally security identification information **MAY** be added to secure the "Submodel API". + +When searching the data assets catalog of a provider, a consumer **SHOULD** use the `assetId` previously +determined via `subprotocolBody` of the SubmodelDescriptor's endpoint definition of subprotocol type "DSP". +Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for the definition of the `subprotocolBody`. + +| **Property** | **Value** | +| --- | --- | +| [https://w3id.org/edc/v0.0.1/ns/id](https://w3id.org/edc/v0.0.1/ns/id) | `{{CONNECTOR_ASSET_ID}}` specified in the DSP endpoint of the SubmodelDescriptor (see [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition)) | + +*Table 8: Connector data assets request properties values* + +An example connector data asset definition is given below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "http://purl.org/dc/terms/", + "aas-semantics": "https://admin-shell.io/aas/3/0/HasSemantics/" + }, + "@id": "{{CONNECTOR_ASSET_ID}}", + "properties": { + "dct:type": {"@id": "cx-taxo:Submodel"}, + "cx-common:version": "3.0", + "aas-semantics:semanticId": {"@id": "urn:samm:io.catenax.delivery_information:2.0.0#DeliveryInformation"} + }, + "privateProperties": { + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ SUBMODEL_ENDPOINT }}", + "proxyQueryParams": "false", + "proxyBody": "false", + "proxyPath": "true", + "proxyMethod": "false", + } +} +``` + +#### 4.1.2 INDUSTRY CORE PART TYPE TWIN REGISTRATION AND DEFINITION + +##### 4.1.2.1 SHELL DESCRIPTOR REGISTRATION + +To allow partners to receive the actual "*Delivery Information*" data as defined in [Chapter 3](#3-aspect-models), +the provider **MUST** register a Shell Descriptor in the dDTR (see [[CX-0002]](#61-normative-references)) so that a partner: + +- May lookup the Industry Core Part Type Twin based on known identification data. +- May identify the connector endpoint providing access to the actual "Delivery Information" submodel data. + +The Shell Descriptors represent each an Industry Core Part Type Twin and **MUST** follow the rules as defined +in [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids). + +The Shell Descriptor **MUST** be configured with the set of properties as defined in the table below. + +| **Object in ShellDescriptor** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***id*** | Defines the technical ID of the Asset Administration Shell representing a partner's twin. | **MUST** be unique following Industry Core Part Type standard [[CX-0126]](#61-normative-references) and is a technical Id randomly assigned as multiple Part Type Twins may be created for one Part Type. E.g. this number differs for the twins created at supplier and customer side. | +| | ***globalAssetId*** | Defines the Catena-X ID of the twin. | **MUST** be aligned with the partner's material. When referring to the same Part Type Twin, the same number **MUST** be used (see [[CX-0126]](#61-normative-references)). | +| | **specificAssetIds** | Identifiers that may be used to lookup Part Type Twins. | **MUST** be set according to the Industry Core Part Type standard [[CX-0126]](#61-normative-references). See Table 10 for respective specific asset IDs. The "customerPartId" **MUST** be set by Customers and **SHOULD** be set by Suppliers. | +| submodelDescriptor | **id** | Technical identifier of a SubmodelDescriptor. | **MUST** be set to a unique identifier. | +| submodelDescriptor | **semanticId** | The semantic identifier of the "Delivery Information" SAMM. | **MUST** be set to `{ "type": "ExternalReference", "keys": [{ "type": "GlobalReference", "value": "urn:samm:io.catenax.delivery_information:2.0.0#DeliveryInformation" }] }` to externally define how the Submodel must be interpreted. | +| submodelDescriptor > endpoint | **interface** | Defines the Submodel Interface (see [[CX-0002]](#61-normative-references)) and the version. | **MUST** be set to "SUBMODEL-3.0" to rely on current specification. | +| submodelDescriptor > endpoint > protocolInformation | **href** | Defines the direct link to the public API of the connector's data plane with a path that **SHOULD** be appended by the proxy, if needed. | **MUST** be set to the public API of the data plane providing the data with the path appended to directly access the submodel. | +| submodelDescriptor > endpoint > protocolInformation | **subprotocol** | Defines the usage of the connector based on DSP to access and use the submodel. | **MUST** be set to "DSP" to define the connector endpoint of the subprotocol. | +| submodelDescriptor > endpoint > protocolInformation | **subprotocolBody** | Defines the asset id in the connector and the connector address to access and use the submodel. | **MUST** be set to `"id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}"` to provide the necessary information for contracting the submodel endpoint. Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for the definition of the asset of the subprotocolBody. | + +*Table 9: Properties relevant for the Shell Descriptor definition* + +When searching the submodel in the dDTR of a provider, a consumer **SHOULD** use the specific asset IDs +as defined in [[CX-0126]](#61-normative-references). Table 10 gives an overview of the specific asset IDs that the data provider +added to the ShellDescriptor so that the data consumer may find the Industry Core Part Type Twin. + +| **Specific Asset Id** | **Value** | +| --- | --- | +| digitalTwinType | "PartType". Set to identify twins compliant to the Industry Core Part Type (see [[CX-0126]](#61-normative-references)). | +| manufacturerId | Supplier / Manufacturer partner BPNL (see [[CX-0010]](#61-normative-references)) | +| manufacturerPartId | Supplier / Manufacturer partner identification number of the part. | +| customerPartId | Customer partner identification number of the part. | + +*Table 10: Specific asset IDs of Industry Core Part Type Twins proposed to be used to lookup a twin in the dDTR* + +The Shell Descriptor defines the metadata of the Industry Core Part Type Twin. The following example +Shell Descriptor represents a supplier's Shell Descriptor of a supplier who provides two customers access +to an "*Delivery Information*" submodel. For further information on the creation of Part Type Twins, +refer to [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids). + +Following [[CX-0002]](#61-normative-references), when searching the data assets catalog of a provider, a consumer **SHOULD** +use the `assetId` determined via `subprotocolBody` of the SubmodelDescriptor's endpoint definition +of subprotocol type `"DSP"` of the Submodel Descriptor of interest. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "id": "{{TECHNIAL_TWIN_ID}}", + "globalAssetId": "{{MATERIAL_NUMBER_CX}}", + "idShort": "Semiconductor", + "specificAssetIds": [ + { + "name": "digitalTwinType", + "value": "PartType", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "manufacturerPartId", + "value": "{{MATERIAL_NUMBER_SUPPLIER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "manufacturerId", + "value": "{{SUPPLIER_BPNL}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "customerPartId", + "value": "{{MATERIAL_NUMBER_CUSTOMER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "customerPartId", + "value": "{{MATERIAL_NUMBER_OTHER_CUSTOMER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + } + ], + "submodelDescriptors": [ + { + "id": "e5c96ab5-896a-482c-8761-efd74777ca97", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.delivery_information:2.0.0#DeliveryInformation" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "{{SUPPLIER_CONNECTOR_DATAPLANE_PUBLIC_API}}/{{PATH_IF_NEEDED}}", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ] + }, + { + "id": "a6c96ab5-896a-482c-8761-efd74777ca99", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.delivery_information:2.0.0#DeliveryInformation" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "{{SUPPLIER_CONNECTOR_DATAPLANE_PUBLIC_API}}/{{PATH_IF_NEEDED}}", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ] + } + ] +} +``` + +##### 4.1.2.2 LOOKING UP A PART TYPE TWIN IN THE DDTR + +To query the dDTR of a data provider, after contracting the usage via the data provider's connector +(see [[CX-0018]](#61-normative-references)), the lookup API (see [[CX-0002]](#61-normative-references)) can be used relying on the specific +asset IDs defined by the Industry Core Part Type (see [[CX-0126]](#61-normative-references)) that can be seen in +Table 10 (table of shellDescriptorRegistration with specific asset IDs). + +An example call relying on all information is given in the code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{PARTNER_CONNECTOR_DATA_PLANE}}/lookup/shells?assetIds={"name":"digitalTwinType", "value": "PartType"},{"name":"manufacturerPartId", "value": "{{MATERIAL_NUMBER_SUPPLIER}}"},{"name":"manufacturerId", "value": "{{SUPPLIER_BPNL}}"},{"name":"customerPartId", "value": "{{MATERIAL_NUMBER_CUSTOMER}}"} +``` + +As a result identifiers of the ShellDescriptors will be returned. With this data, a data provider can +read the ShellDescriptor to extract the endpoint data of the data provider. An example is given in the +code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{PARTNER_CONNECTOR_DATA_PLANE}}/shell-descriptors/{{AAS_IDENTIFIER}} +``` + +##### 4.1.2.3 FETCHING SUBMODEL DATA + +To fetch the *Delivery Information* Submodel data at the submodel endpoint of a data provider, after +contracting the usage via the data provider's connector (see [[CX-0018]](#61-normative-references)), the submodel API (see [[CX-0002]](#61-normative-references)) +can be used. + +An example call relying on all information may be seen in the code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{HREF_PATH}}/$value +``` + +## 5 PROCESSES + +> *This section is normative* + +### 5.1 DELIVERY INFORMATION PROCESS + +The aim of the Catena-X standard is to enable as much transparency between business partners as +possible, provided that the exchange complies with German or EU competition law. The user must be +aware that competitively sensitive information from one supplier or customer **MUST NOT** be shared +with others. This means that *Delivery Information* related to other customers or suppliers **MUST +NOT** be disclosed under any circumstances. The exchange of information must always be direct and +unidirectional. + +The responsibility for the transport may vary depending on the contractual agreements. This responsibility +is defined by the INCOTERM. These are official standards provided by the [International Chamber of Commerce (ICC)](#62-non-normative-references). +At the time of writing this standard there are 11 different INCOTERMS. + +| **Code** | **Short description** | **Definition** | **Place to be specified** | +| --- | --- | --- | --- | +| **EXW** | **EXW**orks | The supplier makes the goods available at their premises, or at another named place. This term places the maximum obligation on the customer and minimum obligations on the supplier. | At the factory site or any other place | +| **FCA** | **F**ree **CA**rrier | The supplier delivers the goods, cleared for export, at a named place (possibly including the supplier's own premises). The goods can be delivered to a carrier nominated by the customer, or to another party nominated by the customer. | Location of the supplier or location of the carrier | +| **FAS** | **F**ree **A**longside **S**hip | The supplier delivers when the goods are placed alongside the customer's vessel at the named port of shipment. This means that the customer has to bear all costs and risks of loss of or damage to the goods from that moment. | Agreed loading port (suitable only for ship loading) | +| **FOB** | **F**ree **O**n **B**oard | The supplier bears all costs and risks up to the point the goods are loaded on board the vessel. The supplier's responsibility does not end at that point unless the goods are "appropriated to the contract" that is, they are "clearly set aside or otherwise identified as the contract goods". | Agreed loading port (suitable only for ship loading) | +| **CFR** | **C**ost And **FR**eight | The supplier pays for the carriage of the goods up to the named port of destination. Risk transfers to customer when the goods have been loaded on board the ship in the country of Export. | Agreed port of destination (suitable only for loading ships) | +| **CIF** | **C**ost **I**nsurance **F**reight | The supplier is responsible for covering the cost, freight, and minimum insurance to transport goods to the named port of destination, with risk transferring to the customer once the goods are loaded onto the shipping vessel. The supplier handles export customs clearance, but the customer is responsible for import customs clearance, unloading, and any further transportation. | Agreed port of destination (suitable only for loading ships) | +| **DAP** | **D**elivered **A**t **P**lace | The supplier delivers when the goods are placed at the disposal of the customer on the arriving means of transport ready for unloading at the named place of destination. The risk passes from supplier to customer from the point of destination mentioned in the contract of delivery. | Agreed delivery and destination location (usually destination terminal or customer´s location) | +| **DPU** | **D**elivered at **P**lace **U**nloaded | The supplier delivers the goods, unloaded, at the named place of destination. The supplier covers all the costs of transport (export fees, carriage, unloading from main carrier at destination port and destination port charges) and assumes all risk until arrival at the destination port or terminal. | Agreed delivery and destination location (usually destination terminal or customer's location) | +| **CPT** | **C**arriage **P**aid **T**o | The supplier pays for the carriage of the goods up to the named place of destination. However, the goods are considered to be delivered when the goods have been handed over to the first or main carrier, so that the risk transfers to customer upon handing goods over to that carrier at the place of shipment in the country of Export. | Agreed destination (usually destination terminal or customer's location) | +| **CIP** | **C**arriage **I**nsurance **P**aid | The supplier is responsible for transporting the goods to a named place and providing insurance for the goods during transit. The risk transfers to the customer once the goods are handed over to the first carrier, but the supplier must pay transport and insurance costs to the specified destination. This term is suitable for all modes of transport, including containerized and multimodal shipments | Agreed destination (usually destination terminal or customer's location) | +| **DDP** | **D**elivered **D**uty **P**aid | The supplier is responsible for delivering the goods to the named place in the country of the customer, and pays all costs in bringing the goods to the destination including import duties and taxes. The supplier is not responsible for unloading. | Agreed delivery and destination location (usually destination terminal or customer's location) | + +*Table 11: International Trade Administration. Incoterms 2020 ([*https://www.trade.gov/know-your-incoterms*](https://www.trade.gov/know-your-incoterms))* + +The incoterms allow three possible scenarios regarding *Delivery Information* responsibility: + +| **Scenario** | **Customer responsibility** | **Supplier responsibility** | +| --- | --- | --- | +| 1 | Entire delivery (e.g., INCOTERM EXW) | None | +| 2 | None | Entire delivery (e.g., INCOTERM DDP) | +| 3 | Partial delivery: arrival (e.g., INCOTERM FAS) | Partial delivery: departure (e.g.,INCOTERM FAS) | + +*Table 12: Scenario overview transport responsibilities* + +More details on each scenario are provided in the following sections. + +### 5.1.1 CUSTOMER IS RESPONSIBLE FOR THE WHOLE DELIVERY (E.G. INCOTERM EXW) + +#### 5.1.1.1 ACTORS AND ROLES + +The following actors and roles occur in the described process. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| Customer | The customer submits an order. They are responsible for organizing the transportation of these parts from the origin to its destination. The customer acts as data provider, because he is responsible for the transport. | The customer provides critical *Delivery Information* to the supplier, including estimated pick-up and arrival times, to ensure coordinated preparation and efficient handling of the ordered parts at both ends. | +| Supplier | The supplier manufactures parts and makes them available at their origin. The supplier acts as a data consumer, because the consumer is responsible for the transport. | The supplier provides necessary information to the customer, including details about the availability and readiness of the parts for pick-up, contributing to an effective coordination of the transportation process. | + +*Table 13: Actors and roles scenario 1* + +#### 5.1.1.2 PROCESS PRESENTATION + +In this scenario, the customer is responsible for organizing the pick-up of items from the +supplier's location (origin) and their transportation to the customer's location. For transparency, +the supplier requests *Delivery Information* from the customer. The customer responds with both the +departure times and quantities, ensuring the supplier knows when to have the items ready for pick +up. Additionally, the customer informs the supplier of the items' estimated arrival times at the +destination facility. + +| **Delivery information** | **-1** | **Today** | **+1** | **+2** | **+3** | +| --- | --- | --- | --- | --- | --- | +| **Departure** | 100 | 500 | 300 | 200 | 500 | +| **Arrival** | 800 | 100 | 500 | 0 | 300 | + +*Table 14: Delivery Information example scenario 1* + +Since the semantic model applies to different scenarios, the mandatory nature of eventTypes cannot be +fully addressed in the model. Data **MUST** be provided according to the following restrictions: + +- The customer **MUST** provide the departure information and **MUST** provide arrival information to + give a benefit back to the supplier. +- If there is no confirmed date and time, the supplier can use a default estimation for the arrival + information (e.g. departure date + 3 days). + +There **MUST** be a departure information because the supplier needs to know when the goods will be picked up. + +There **MUST** be arrival information to give the supplier more transparency. + +### 5.1.2 SUPPLIER IS RESPONSIBLE FOR THE WHOLE DELIVERY (E.G. INCOTERM DDP) + +#### 5.1.2.1 ACTORS AND ROLES + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| Customer | The customer submits an order. The customer acts as a data consumer, because the supplier is responsible for the transport. | The customer submits an order at the supplier (quantity, location, preferred date).| +| Supplier | The supplier manufactures parts and makes them available. They are responsible for organizing the transportation of these parts from the origin to the destination. The supplier acts as data provider, because he is responsible for the transport. | The supplier coordinates all aspects of the delivery process, including selecting transportation methods, scheduling shipments, and providing the customer with regular updates on the delivery status and estimated arrival times. | + +*Table 15: Actors and roles scenario 2* + +#### 5.1.2.2 PROCESS REPRESENTATION + +In this case, the supplier takes on the responsibility of organizing the entire delivery process +from their facilities (origin) to the customer's destination. This includes arranging for the +transportation of the items and ensuring they reach the customer's facility. The supplier must also +maintain transparency throughout the process. They inform the customer of the departure times and +quantities, ensuring the customer is aware of when to expect the delivery. Furthermore, the supplier +provides updates on the delivery progress, including the estimated arrival times at the customer's +facility, thus keeping the customer informed at every stage of the delivery process. + +**Transport information is only provided to the supplier.** + +| **Delivery information** | **-1** | **Today** | **+1** | **+2** | **+3** | +| --- | --- | --- | --- | --- | --- | +| **Departure** | 200 | 400 | 300 | 200 | 500 | +| **Arrival** | 600 | 300 | 500 | 10 | 300 | + +*Table 16: Delivery Information example scenario 2* + +As the semantic model applies to different scenarios, the mandatoryness of eventTypes can not be fully +handled in the model. Data **MUST** be provided according to the following restrictions: + +- The supplier **MUST** provide the estimated arrival information and **MUST** provide the departure + information. +- If there is no confirmed date and time, the supplier can use a default estimation for the arrival + information (e.g. departure date + 3 days). + +There **MUST** be an arrival information because the customer needs to know when the goods will be available in the customer's factory. +There **MUST** be departure information, to give the customer more transparency. + +### 5.1.3 RESPONSIBILITY FOR THE DELIVERY IS SPLIT BETWEEN SUPPLIER AND CUSTOMER (E.G. INCOTERM FAS) + +#### 5.1.3.1 ACTORS AND ROLES + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| Customer | The customer submits an order. The customer is responsible for one half of the delivery. The customer acts as a data provider, because he is responsible for one half of the transport, and as a data consumer, because the supplier is responsible for the other half of the transport. | The customer coordinates and manages one part of the delivery process, which includes arranging transportation for the latter half of the journey, ensuring the parts are received from the midpoint, and providing necessary information to the supplier. | +| Supplier | The supplier manufactures parts and makes them available. The supplier is responsible for one half of the delivery. The supplier acts as a data provider, because he is responsible for one half of the transport, and as a data consumer, because the customer is responsible for the other half of the transport. | The supplier handles the initial part of the delivery process, including transporting the parts to a designated midpoint. | + +*Table 17: Actors and roles scenario 3* + +#### 5.1.3.2 PROCESS PRESENTATION + +In this case the supplier is responsible for only one part of the transport (e.g. from departure +from its factory (origin) until a middle point) and the customer takes over the responsibility for +the rest of the transport (e.g. from middle point to its factory (destination)). In this case both +customer and supplier can request *Delivery Information* of the other party. + +**Example:** + +Supplier A is in charge of the initial part of the transport, handling the pick-up and delivery of +items from its location to a designated middle point. Customer A takes over the transport from the +middle point, needs specific details about this first leg of the journey. Therefore, Customer A +requests critical *Delivery Information* from Supplier A, such as departure time, pick-up location, +and the quantity of items. + +| **Delivery information** | **-1** | **Today** | **+1** | **+2** | **+3** | +| --- | --- | --- | --- | --- | --- | +| Departure | 100 | 500 | 300 | 200 | 500 | + +*Table 18: Delivery Information example scenario 3* + +Customer A assumes responsibility for the transport of goods from a predetermined middle point to +its destination. Therefore, to gain transparency, Supplier A requests *Delivery Information* from +Customer A, such as the estimated arrival times, final destination (e.g. Customer A's factory), and +the quantity of goods to be shipped. + +| **Delivery information** | **-1** | **Today** | **+1** | **+2** | **+3** | +| --- | --- | --- | --- | --- | --- | +| **Arrival** | 800 | 100 | 500 | 0 | 300 | + +*Table 19: Delivery Information example scenario 4* + +As the semantic model applies to different scenarios, the mandatoryness of eventTypes can not be fully +handled in the model. Data **MUST** be provided according to the following restrictions: + +- The supplier **MUST** provide the departure information. +- The client **MUST** provide the arrival information. + +There **MUST** be departure information, to give the customer more transparency. + +There **MUST** be arrival information, to give the supplier more transparency. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normative* + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [CX-0001] | EDC Discovery API | 1.0.2 | +| [CX-0002] | Digital Twins in Catena-X | 2.2.0 | +| [CX-0003] | SAMM Aspect Meta Model | 1.1.0 | +| [CX-0006] | Registration and initial onboarding | 2.0.0 | +| [CX-0010] | Business Partner Number (BPN) | 2.0.0 | +| [CX-0018] | Dataspace Connectivity | 3.0.0 | +| [CX-0053] | Discovery Finder and BPN Discovery Service APIs | 1.1.0 | +| [CX-0120] | Short Term Material Demand Exchange | 2.0.0 | +| [CX-0121] | Planned Production Output Exchange | 2.0.0 | +| [CX-0122] | Item Stock Exchange | 2.0.0 | +| [CX-0126] | Industry Core Part Type | 2.0.0 | +| [CX-0145] | Days of Supply Exchange | 1.0.0 | +| [CX-0146] | Supply Chain Disruption Notifications | 1.0.0 | + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +| **Context** | **Link** | +| --- | --- | +| [CX-OMW] | Catena-X Operating Model Whitepaper. Download from: [https://catena-x.net/fileadmin/\_online\_media\_/CX\_Operating\_Modelv2.1\_final.pdf](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf) | +| [CX-ODRL] | Catena-X ODRL Profile repository: https://github.com/catenax-eV/cx-odrl-profile | +| [RFC2119] | Bradner, S. Key words for use in RFCs to Indicate Requirement Levels. Available online: https://datatracker.ietf.org/doc/html/rfc2119 | +| [RFC8174] | Leiba, B. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. Available online: https://datatracker.ietf.org/doc/html/rfc8174 | +| [SMT] | How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf | +| [IDTA-01002-3-0] | Specification of the Asset Administration Shell Part 2: Application Programming Interfaces. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API.pdf | + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_1.svg b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_1.svg new file mode 100644 index 000000000..4f4d7cd6a --- /dev/null +++ b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_1.svg @@ -0,0 +1,4 @@ + + + +
    Data Provider
    Data Provider
    Connector
    Connector
    Busines Application
    Busines App...
    Catena-X Core Service Provider
    Catena-X Core Service Provider
    IAM
    IAM
    Credential Service
    Credential S...
    Keycloak
    Keycloak
    Data Consumer
    Data Consumer
    Connector
    Connector
    Busines Application
    Busines Applicati...
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
    (8) Get Submodel
    (8) Get Su...
    (5) Query dDTR for Twin and submodel
    (5) Query dDTR for Twin and submodel
    (4) Connector Communication
      (Catalog / Contracting / Transfer)  
    (4) Connector Communication...
    dDTR
    dDTR
    Submodel Endpoint
    Submodel E...
    (10) Get Submodel
    (10) Get S...
    (3) Register Twin
    with Submodels
    (3) Register Twin...
    (2) Register Submodel Endpoint
     at Connector
    (2) Register Submodel Endpoint...
    (9)
    (9)
    Text
    Text
    (6) Get lookup/shells
    by specific asset ids
    (6) Get lookup/shells...
    (1) Register dDTR at Connector
    (1) Register dDTR at Connector
    (7) Get shell-descriptors
    by AAS ID
    (7) Get shell-descriptors...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_2.svg b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_2.svg new file mode 100644 index 000000000..7b320801b --- /dev/null +++ b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_2.svg @@ -0,0 +1,4 @@ + + + +
    represents same material
    equivalent specific asset IDs, global asset ID,
    different AAS ID
    represents same material...
    PartType for Material (e.g. "Semiconductor")
    PartType for Material...
    Supplier
    Supplier
    Customer
    Custom...
    Asset
    registered in dDTR as AAS
    Asset...
    Submodel
    Submodel
    PartType for Material "Control Unit"
    PartType for Materia...
    DeliveryInformation
    DeliveryInformation
    DeliveryInformation
    DeliveryInformation
    PartTypeInformation
    PartTypeInformation
    SingleLevelUsageAs Planned
    SingleLevelUsageAs P...
    submodel of
    submodel of
    submodel of
    submodel of
    references twin
    references twin
    PartTypeInformation
    PartTypeInformation
    SingleLevel
    BomAsPlanned
    SingleLevel...
    references twin
    references twin
    submodel of
    submodel of
    submodel of
    submodel of
     Legend
     Legend
    Digital Twin in DTR
    Digital Twin in DTR
    Submodel (CX - 0118)
    Submodel (CX - 0118)
    Submodel (IC Part Type)
    Submodel (IC Part Type)
    submodel of
    submodel of
    references twin
    references twin
    PartType for Material "Semiconductor"
    PartType for Materia...
    submodel of
    submodel of
    submodel of
    submodel of    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_3.puml b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_3.puml new file mode 100644 index 000000000..f46a51236 --- /dev/null +++ b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_3.puml @@ -0,0 +1,43 @@ +@startuml Figure_3 +title Shared Digital Approach - Registration of IC Part Type Twin + +autonumber + +box "Supplier" #LightBlue + participant SupplierApplication as "Application" + participant SupplierDTR as "dDTR" + participant SupplierSubmodelEndpoint as "Submodel Endpoint" + participant SupplierEDC as "Connector" +end box + +box "Customer" #LightGreen + participant CustomerEDC as "Connector" + participant CustomerSubmodelEndpoint as "Submodel Endpoint" + participant CustomerDTR as "dDTR" + participant CustomerApplication as "Application" +end box + +== Supplier registers IC Part Type Twin with Submodel for Customer == + + note over SupplierApplication, SupplierSubmodelEndpoint: Supplier created Part Type Twin + + +== Customer registers IC Part Type Twin with Submodel for Supplier == + CustomerApplication -> CustomerEDC: Register dDTR for partner at Connector + activate CustomerEDC + return OK + + note over CustomerSubmodelEndpoint, CustomerApplication: Keeping Submodel updated only needed\nfor repository pattern + CustomerApplication -> CustomerSubmodelEndpoint: Create Submodel + activate CustomerSubmodelEndpoint + return OK + + CustomerApplication -> CustomerEDC: Register endpoint of Submodel for READ access for partner at Connector + activate CustomerEDC + return OK + + CustomerApplication -> CustomerDTR: Register IC Part Type Twin Shell Descriptor\n with Submodel endpoint\nfor Partner in dDTR\n(DSP endpoint) + activate CustomerDTR + return OK + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_3.svg b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_3.svg new file mode 100644 index 000000000..7372884ad --- /dev/null +++ b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_3.svg @@ -0,0 +1,53 @@ +Shared Digital Approach - Registration of IC Part Type TwinSupplierCustomerApplicationApplicationdDTRdDTRSubmodel EndpointSubmodel EndpointConnectorConnectorConnectorConnectorSubmodel EndpointSubmodel EndpointdDTRdDTRApplicationApplicationSupplier registers IC Part Type Twin with Submodel for CustomerSupplier created Part Type TwinCustomer registers IC Part Type Twin with Submodel for Supplier1Register dDTR for partner at Connector2OKKeeping Submodel updated only neededfor repository pattern3Create Submodel4OK5Register endpoint of Submodel for READ access for partner at Connector6OK7Register IC Part Type Twin Shell Descriptorwith Submodel endpointfor Partner in dDTR(DSP endpoint)8OK \ No newline at end of file diff --git a/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_4.puml b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_4.puml new file mode 100644 index 000000000..e42c97417 --- /dev/null +++ b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_4.puml @@ -0,0 +1,84 @@ +@startuml Figure_4 +title Shared Digital Twin Approach - Lookup of IC Part Type Twin + +autonumber + +box "Supplier" #LightBlue + participant SupplierApplication as "Application" + participant SupplierDTR as "dDTR" + participant SupplierSubmodelEndpoint as "Submodel Endpoint" + participant SupplierEDC as "Connector" +end box + +box "Customer" #LightGreen + participant CustomerEDC as "Connector" + participant CustomerSubmodelEndpoint as "Submodel Endpoint" + participant CustomerDTR as "dDTR" + participant CustomerApplication as "Application" +end box + + +== Customer updates Submodel information (repository pattern only) == + note over CustomerSubmodelEndpoint, CustomerApplication: Keeping Submodel updated only needed\nfor repository pattern + CustomerApplication -> CustomerSubmodelEndpoint: Update Submodel information + activate CustomerSubmodelEndpoint + return OK + + +== Supplier reads (updated) Submodel from Customer == + + SupplierApplication -> SupplierEDC: Query Connector Catalog for Customer dDTR access + activate SupplierEDC + + SupplierEDC <-> CustomerEDC: DSP communication + + return Catalog + + SupplierApplication -> SupplierEDC: Negotiate Contract and init transfer + activate SupplierEDC + SupplierEDC <-> CustomerEDC: DSP communication + return OK + + SupplierApplication -> CustomerEDC: Query DTR for IC Part Type Twin based on specific asset ids + activate CustomerEDC + CustomerEDC -> CustomerDTR: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerDTR + CustomerDTR --> CustomerEDC + deactivate CustomerDTR + return ShellDescriptor Ids + + SupplierApplication -> SupplierApplication: select ShellDescriptor ID\nto get ShellDescriptor for\nIC PartType Twin + + SupplierApplication -> CustomerEDC: Lookup IC Part Type Twin based on ShellDescriptor Id + activate CustomerEDC + CustomerEDC -> CustomerDTR: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerDTR + CustomerDTR --> CustomerEDC + deactivate CustomerDTR + return ShellDescriptor + + SupplierApplication -> SupplierApplication: Extract DSP Endpoint and Connector Asset ID for Submodel + + SupplierApplication -> SupplierEDC: Query Connector Catalog for Submodel based on Connector Asset ID + activate SupplierEDC + + SupplierEDC <-> CustomerEDC: DSP communication + + return Catalog + + SupplierApplication -> SupplierEDC: Negotiate Contract for Submodel and init transfer + activate SupplierEDC + SupplierEDC <-> CustomerEDC: DSP communication + return OK + + SupplierApplication -> CustomerEDC: Read Submodel + activate CustomerEDC + CustomerEDC -> CustomerSubmodelEndpoint: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerSubmodelEndpoint + CustomerSubmodelEndpoint --> CustomerEDC + deactivate CustomerSubmodelEndpoint + return Submodel + + SupplierApplication -> SupplierApplication: Use Submodel + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_4.svg b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_4.svg new file mode 100644 index 000000000..fa3889e45 --- /dev/null +++ b/docs/standards/CX-0118-ActualDeliveryInformationExchange/assets/Figure_4.svg @@ -0,0 +1,94 @@ +Shared Digital Twin Approach - Lookup of IC Part Type TwinSupplierCustomerApplicationApplicationdDTRdDTRSubmodel EndpointSubmodel EndpointConnectorConnectorConnectorConnectorSubmodel EndpointSubmodel EndpointdDTRdDTRApplicationApplicationCustomer updates Submodel information (repository pattern only)Keeping Submodel updated only neededfor repository pattern1Update Submodel information2OKSupplier reads (updated) Submodel from Customer3Query Connector Catalog for Customer dDTR access4DSP communication5Catalog6Negotiate Contract and init transfer7DSP communication8OK9Query DTR for IC Part Type Twin based on specific asset ids10forward request based on Connector asset definitions(consumer proxy)11 12ShellDescriptor Ids13select ShellDescriptor IDto get ShellDescriptor forIC PartType Twin14Lookup IC Part Type Twin based on ShellDescriptor Id15forward request based on Connector asset definitions(consumer proxy)16 17ShellDescriptor18Extract DSP Endpoint and Connector Asset ID for Submodel19Query Connector Catalog for Submodel based on Connector Asset ID20DSP communication21Catalog22Negotiate Contract for Submodel and init transfer23DSP communication24OK25Read Submodel26forward request based on Connector asset definitions(consumer proxy)27 28Submodel29Use Submodel \ No newline at end of file diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/CX-0120-ShortTermMaterialDemandExchange.md b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/CX-0120-ShortTermMaterialDemandExchange.md new file mode 100644 index 000000000..12deed448 --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/CX-0120-ShortTermMaterialDemandExchange.md @@ -0,0 +1,984 @@ +# CX-0120 Short-Term Material Demand Exchange 2.0.0 + +## ABSTRACT + +This document defines the standardized exchange of *Short-Term Material Demand* data within the +Catena-X network. With a focus on addressing shortages and enhancing efficiency across supply +chains, this standard aims to facilitate the consistent, reliable, and secure transmission of +*Short-Term Material Demand* data among network participants. It serves as a foundational resource +for developers, solution providers, and participants in the Catena-X network by offering +comprehensive guidance on implementing and adhering to the standardized exchange of *Short-Term +Material Demand* data. The standardization of the customer's *Short-Term Material Demand* semantics +and exchange API enables participants in the supply chain to share information about time-bound +*Short-Term Material Demand* quantities at a customer's site in an interoperable manner. To give +additional context and guidance, specific process descriptions with examples are used to convey an +understanding of the application. + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +Changes: + +- integration and usage of digital twins as defined in [[CX-0002]](#61-normative-references) Digital Twins in Catena-X +- harmonization of aspect model in accordance with [[CX-0126]](#61-normative-references) Industry Core: Part Type +- new specific submodel `io.catenax.short_term_material_demand:1.0.0:ShortTermMaterialDemand` from + `io.catenax.material_demand:1.0.0:MaterialDemand` +- discontinuation of the proprietary API used in v1.0.0 of this standard +- grammatical, spelling and semantic improvements + +New Content: + +- added a note on the obligation of standard implementers to make aware that sensitive data is being + handled, see [[Chapter 2.1.3]](#213-additional-requirements) + +## 1 INTRODUCTION + +In recent years global supply chains have significantly been affected by global crises. +Ever-increasing complexity and interdependencies compound this issue. As a result small and +medium-sized enterprises as well as large enterprises are exposed to an increased risk of +disruptions in their supply chains. To adapt to short-term fluctuations and develop the right +countermeasures, it is essential to have sound information about the *Short-Term Material Demand* of +customers. + +This document describes and standardizes a common semantic model for the *Short-Term Material Demand* as well as an associated API to exchange *Short-Term Material Demand* information between +supply chain partners in an interoperable manner. The customer's *Short-Term Material Demand* is +the quantity of a material that a customer requests from a supplier in a time horizon of up to four +weeks. It aims to supplement, not to replace or to duplicate, regular and legally binding orders or +call-offs between partners and enable customers to provide suppliers with context regarding their +demands. It is possible to distinguish in particular between those demands that are critical for the +customer's planned production and those that are additional and possibly non-recurring, e.g. for +building up safety stocks. Suppliers can use this additional information to better coordinate their +own production and demands and to proactively propose solutions in the event of shortages. + +Through the adoption of this standard, supply chain partners can efficiently communicate *Short-Term +Material Demand* information, that supports proactive and better-founded decision-making, responsive +inventory management, and effective allocation of resources to prevent or mitigate shortages. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following roles defined in [[CX-OMW]](#62-non-normative-reference): + +- **Data Providers** willing to provide *Short-Term Material Demand* data +- **Data Consumers** interested in requesting and receiving *short-term* *material demand* data +- **Business Application Providers** interested in providing solutions implementing this standard +- **Consulting Services Providers** interested in supporting companies fulfilling the standard + +The scope of this standard is only the *Short-Term Material Demand* aspect model and API. It describes +the exchange of *Short-Term Material Demand* data through a connector in accordance to [[CX-0018]](#61-normative-references). + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +The customer's demand is one of the key information a supplier or manufacturer uses to plan his +production. The customer order represents this demand towards the supplier or customer. The +*Short-Term Material Demand* is intended to be additional information to evaluate the partners' +supply situation. The respective orders or call-offs communicated, are still contractually binding. +The actions to take based on the material demand data described in this standard must be aligned +between the customer and supplier. + +*Figure 1* shows the high-level architecture of the *Short-Term Material Demand* exchange in the +Catena-X dataspace and the services that are involved. Both the data consumer and the data provider +must be members of the Catena-X network in order to communicate with each other. With the help of +the Credential Service and the Identity Access Management (IAM) each participant can authenticate +itself, verify the identity of the requesting party and decide whether to authorize the request. +The *Short-Term Material Demand* is provisioned in accordance with [[CX-0002]](#61-normative-references). + +![Figure 1: high-level architecture of the Short-Term Material Demand exchange in the Catena-X](./assets/Figure_1.svg) +*Figure 1: high-level architecture of the Short-Term Material Demand exchange in the Catena-X* + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. The key +words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and +**SHOULD NOT** in this document are to be interpreted as described in [[BCP 14]](#62-non-normative-references) [[RFC2119]](#62-non-normative-references) +[[RFC8174]](#62-non-normative-references) when, and only when, they appear in all capitals, as shown here. All participants and +their solutions will need to prove, that they are conform with the Catena-X standards. + +All participants and their solutions will need to prove, that they are conform with the Catena-X +standards. To validate that the standards are applied correctly, Catena-X employs Conformity +Assessment Bodies (CABs). The proof of conformity for a single semantic model is done according to +the general rules for proving the conformity of data provided to a semantic model or the ability to +consume the corresponding data. Furthermore, participants agree to follow the normative language of +this standardization document and to implement the required API-Endpoints described in [Chapter 4](#4-application-programming-interfaces). + +### 1.4 EXAMPLES + +> *This section is non-normative* + +The following example shows a value-only JSON representation of an "Short-Term Material Demand" aspect +model. It contains a demand quantity of 180 pieces with a demand category `"series"` and a demand +quantity of `100` pieces with demand category `"after-sales"` for material with Catena-X ID +`"urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df"`. Also the customer location varies for the different +demand series. This *Short-Term Material Demand* is the demand that a supplier received from a customer. + +```json +{ + "materialGlobalAssetId": "urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df", + "demandSeries": [ + { + "lastUpdatedOnDateTime" : "2023-11-05T08:15:30.123-05:00", + "expectedSupplierLocation": "BPNS8888888888XX", + "demands": [ + { + "demand": { + "value": 180, + "unit" : "unit:piece" + }, + "day" : "2023-10-09" + } + ], + "customerLocation": "BPNS9090909090YY", + "demandCategory": { + "demandCategoryCode": "SR99" + } + }, + { + "expectedSupplierLocation": "BPNS8888888888XX", + "lastUpdatedOnDateTime" : "2023-11-05T08:15:30.123-05:00", + "demands": [ + { + "demand": { + "value": 100, + "unit" : "unit:piece" + }, + "day" : "2023-10-09" + } + ], + "customerLocation": "BPNS5555555555XX", + "demandCategory": { + "demandCategoryCode": "A1S1" + } + } + ] +} +``` + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +| **Name** | **Abrv.** | **Description** | +| --- | --- | --- | +| **Business Partner Number** | BPN | A BPN is the unique identifier of a partner within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Business Partner Number Legal Entity** | BPNL | A BPNL is the unique identifier of a partner legal entity within Catena-X as defined in [CX-0010]. | +| **Business Partner Number Site** | BPNS | A BPNS is the unique identifier of a partner site within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Business Partner Number Address** | BPNA | A BPNA is the unique identifier of a partner address within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Demand** | | Quantity of a demand for a given time frame. The quantity must be greater than or equal to 0 and less or equal than 999999999999999999.999. It allows up to 12 digits and 3 decimal places. | +| **Demand series** | | The demands for a dedicated material in a given time period of a given demand rate, distinguished by their demand location and demand category. | +| **Demand category** | | Classification of demands used for prioritization or allocation. | +| **Order** | | Request from a customer towards a supplier to manufacture / supply a given quantity of a specific product in a predefined time frame. | +| **Provider** | | The party providing the *Short-Term Material Demand* data. This is always the customer. | +| **Consumer** | | The party requesting and consuming the *Short-Term Material Demand* data provided by the provider. This is always the Supplier. Additional terminology used in this standard can be looked up in the glossary on the association homepage. | +| **Customer** | | The recipient of products ordered from / manufactured by a supplier. | +| **Supplier** | | The supplier / manufacturer of a product. | +| **Stock** | | Two-way direction of material on stock:
    - One can have a stock of material which is ready for delivery to customers.
    - One can have a stock of material which can be used for the own production.
    Within this document, the term material, product, component or item refers to any kind of product that may be either be used as input or output of the production. Semi-finished goods are not intended to be covered. | +| **Material Number** | | Unique number of a component or material. | +| **Material** | | The term material is used as a catalogue item in the meaning of the Industry Core Part Type ([[CX-0126]](#61-normative-references)). Whenever referring to material also products, components or items are considered. Semi-finished goods are not intended to be covered. | +| **Digital Twin** | DT | Digital representation of an asset that provides data on aspects of the represented data following [[CX-0002]](#61-normative-references). | +| **decentralized Digital Twin Registry** | dDTR | Component providing registration and discovery API implementations following [[CX-0002]](#61-normative-references). Sometimes referred to without the "decentralized" BUT in Catena-X those are always decentralized. | +| **Asset Administration Shell** | AAS | Technical concept for Digital Twins consisting of different standards. Application in Catena-X is described in Digital Twins in Catena-X standard ([[CX-0002]](#61-normative-references)) | +| **Shell Descriptor** | | Technical concept of the AAS API describing metadata of an Asset Administration Shell representing a Digital Twin. It holds several identification information and meta-information about which submodels are available and where to get the data from (see [[CX-0002]](#61-normative-references), [[IDTA-01002-3-0]](#62-non-normative-reference)). There may exist multiple Shell Descriptor for the same represented Asset (see [[CX-0126]](#61-normative-references)). | +| **Submodel Descriptor** | | Technical concept of the AAS API describing metadata of Submodels within a Shell Descriptor (Asset Administration Shell) (see [[CX-0002]](#61-normative-references), [[IDTA-01002-3-0]](#62-non-normative-reference)). | +| **Specific Asset Ids** | | Identifiers of the Shell Descriptor (Asset Administration Shell) that refer to common identification data for an asset/material at hand e.g., manufacturer part Id. Common specific asset ids used for identification are described in Industry Core Part Type Standard (see [[CX-0126]](#61-normative-references)). | +| **Asset Administration Shell Identifier** | AAS ID | Also referred to as Shell Descriptor id, is the technical identifier of the Shell Descriptor. | +| **Global Asset Id** | | Also referred to as Catena-X Id, is the Catena-X identifier for assets represented by Digital Twins (see [[CX-0126]](#61-normative-references)). | +| **Aspect** | | A domain-specific view on information and functionality associated with a specific Digital Twin with a reference to a concrete Aspect Model (see [[CX-0002]](#61-normative-references)). Within Catena-X, an aspect is formally described using the Semantic Aspect Meta Model (see [[CX-0003]](#61-normative-references)). | +| **Semantic Id** | | Identifier including namespace to specify the semantic description of submodels using the Semantic Aspect Meta Model (SAMM). It allows partners to know the exact data format and semantics when e.g., browsing catalogs (see [[CX-0003]](#61-normative-references)). | +| **Data Space Protocol** | DSP | A set of specifications designed to facilitate interoperable data sharing between entities governed by usage control and based on Web technologies. These specifications define the schemas and protocols required for entities to publish data, negotiate Agreements, and access data as part of a Dataspace. It is governed by the International Data Spaces Association. Connectors compliant to [[CX-0018]](#61-normative-references) support the Data Space Protocol. | +| **Shared Asset Approach** | | Digital twin pattern in which each party has a twin for the same asset (Part Type). They share the same identification data in terms of specific asset IDs and global asset ID. The digital twins do have different technical identifiers. | + +*Table 1: Terminology Short-Term Material Demand Standard* + +Additional terminology used in this standard can be looked up in the glossary on the association's homepage + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +### 2.1 "SHORT-TERM MATERIAL DEMAND" + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +The following Catena-X standards are prerequisites for the implementation of this standard and therefore +**MUST** be considered / implemented by the relevant parties specified in each of them. + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0001]](#61-normative-references) | EDC Discovery API | 1.0.2 | +| [[CX-0002]](#61-normative-references) | Digital Twins in Catena-X | 2.2.0 | +| [[CX-0003]](#61-normative-references) | SAMM Aspect Meta Model | 1.1.0 | +| [[CX-0006]](#61-normative-references) | Registration and initial onboarding | 2.0.0 | +| [[CX-0010]](#61-normative-references) | Business Partner Number (BPN) | 2.0.0 | +| [[CX-0018]](#61-normative-references) | Dataspace Connectivity | 3.0.0 | +| [[CX-0126]](#61-normative-references) | Industry Core Part Type | 2.0.0 | + +*Table 2: List of mandatory standards* + +The usage of this standard may be complemented with the following Catena-X standards to further extend +the range of shortage prevention possibilities: + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0118]](#61-normative-references) | Delivery Information Exchange | 2.0.0 | +| [[CX-0121]](#61-normative-references) | Planned Production Output Exchange | 2.0.0 | +| [[CX-0122]](#61-normative-references) | Item Stock Exchange | 2.0.0 | +| [[CX-0145]](#61-normative-references) | Days of Supply Exchange | 1.0.0 | +| [[CX-0146]](#61-normative-references) | Supply Chain Disruption Notifications | 1.0.0 | + +*Table 3: List of non-mandatory complementary standards* + +#### 2.1.2 DATA REQUIRED + +No additional data requirements. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### CONVENTIONS FOR USE CASE POLICY IN CONTEXT DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization +of data within the Catena-X use cases has been outlined. A set of specific policies on data offering +and data usage level detail the conditions under which data may be accessed, shared, and used, +ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data +usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository [[CX-ODRL]](#62-non-normative-references). This document provides in-depth explanations of the + terms and conditions applied to data access and utilization, ensuring that all engagement with our data + is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. + Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +###### ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for +members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, +Data Provider maintains control over its anti-trust obligations when sharing certain data. In +particular, Data Provider may apply Access Policies to restrict access to a particular data offer +for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +###### ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use +the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are +provided via the ODRL policy repository [[CX-ODRL]](#62-non-normative-references). + +##### REMINDER OF ANTITRUST + +Notice and/or acknowledgement concepts to raise awareness of antitrust issues during use of this standard +are **RECOMMENDED**, for example through the implementation of a help desk or pop-up info. + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +This standard builds upon the Industry Core Part Type [[CX-0126]](#61-normative-references) and the Digital Twins in +Catena-X [[CX-0002]](#61-normative-references) standards. It follows the following design patterns: + +- Usage of Digital Twins as shared assets to follow a pull approach for data. +- Usage of the specific asset IDs and further identification data for the Digital Twin for the Part Type + (see [[CX-0126]](#61-normative-references)). +- Provisioning of the *PartTypeInformation* on supplier side (see [[CX-0126]](#61-normative-references)). + +Because both parties may provide data regarding different aspects of the same Part Type Twin, they need +to use the same identification data to pinpoint it. + +- The supplier of the part has a Digital Twin representation and is then able to offer + *Short-Term Material Demand* data to customers. +- The customer, who orders or uses the part, has a Digital Twin representation to offer + *Short-Term Material Demand* data to a supplier. +- Both twins refer to the same asset and provide complementary information. They share the same + identification data in two partners' context. + - The supplier + - **MUST** create the Digital Twin first. + - **MUST** generate the Catena-X ID and ensure that the customer-specific asset IDs and submodel + descriptors are only accessible by the specific customer. + - **MAY** use the Digital Twin for multiple customers. + - The customer + - **MUST** create one Digital Twin per supplier. + - **MUST** use the Catena-X ID generated by the supplier. + +The definition of identification data (Catena-X ID, Asset Administration Shell ID, specific asset ID) +**MUST** follow the Industry Core Part Type [[CX-0126]](#61-normative-references). Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for further details. + +> ***Note:*** The Part Type Twin's data is considered sensitive. Data providers **MUST** implement appropriate +measures ensuring that competitors-specific asset IDs and/or information about submodels is accessible +only to the data consumers it concerns, but not to their competitors. + +Figure 2 shows how the shared asset approach is realized. The orange lines show which submodels belong +to the respective AAS. All *Short-Term Material Demand* specific submodels are bound to the specific +Part Type's context e.g., meaning that the *Short-Term Material Demand* aspect is described for the specific +catalog item on supplier and customer side represented by the AASs. The orange submodels are the +submodels used within this standard's context. The grey submodels are used within the Industry Core +[[CX-0126]](#61-normative-references)(*PartTypeInformation, SingleLevelBomAsPlanned, SingleLevelUsageAsPlanned*). +The blue dashed lines show the references between DTs based on Catena-X UUIDs and BPNL information that +may be resolved by the Item Relationship Service (see [[CX-0126]](#61-normative-references)). + +![Figure 2: Conceptual levels of provisioning digital twins in the shared asset approach.](./assets/Figure_2.svg) +*Figure 2: Conceptual levels of provisioning digital twins in the shared asset approach.* + +Figure 2 details two conceptual levels: + +- The Asset level contains the asset (Industry Core Part Type) represented by a Digital Twin. + The latter is provisioned as an Asset Administration Shell (AAS) within the decentralized Digital + Twin Registry (dDTR) of the data provider (supplier or customer). +- The Submodel level represents the actual information that are held by a Digital Twin (DT). Those + submodels follow the respective definition of the in Semantic Aspect Meta Model (SAMM) format + (see [Chapter 3](#3-aspect-models)). The dDTR only holds metadata about the Submodel + (e.g. kind of submodel via semantic ID or connector endpoint information). + +## 3 ASPECT MODELS + +> *This section is normative* + +### 3.1 "SHORT-TERM MATERIAL DEMAND" ASPECT MODEL + +#### 3.1.1 INTRODUCTION + +This section describes the *"Short-Term Material Demand"* semantic model. +It defines the demand of material, product, component or items for a customer. +For the complete semantics and detailed description of its properties refer to the SAMM model in +[Chapter 3.1.5.1.](#3151-rdf-turtle) + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the +"semantic-driven workflow" to create a submodel template specification [[SMT]](#62-non-normative-reference). + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [[CX-0003]](#61-normative-references) as +input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to [[CX-0003]](#61-normative-references). + +##### 3.1.2.1 SHORT-TERM MATERIAL DEMAND CATEGORY HANDLING + +The Material Demand data **MUST** consider the following demand categories shared with the DCM +standard [CX-0128](#61-normative-references). These Demand Categories **MAY** be used optionally. If no categories are to be +used, the value "default" **MUST** be selected. If different categories apply, it is **RECOMMENDED** +to use them to describe certain use cases such as inventory build-up, logistics optimization or +series start-ups. This use case-specific categorization can be an important building block for the +supplier to leverage potential in the event of possible bottlenecks or supply gaps. Demand data for +demand category "Extraordinary Demand" **MAY** be set to actively indicate differences between +call-offs or orders and the demand derived from the scheduled or planned production. + +| Demand Category | Description | Demand Category Code (Based on Data Model) | +| --- | --- | --- | +| Default | No Assignment | `0001` | +| After-Sales | After sales demand of spare parts | `A1S1` | +| Series | Dependent demand e.g. production, assembly, raw material | `SR99` | +| Phase-In-Period | Ramp up of a new product or new material introduction | `PI01` | +| Single-Order | Demand outside the normal spectrum of supply | `OS01` | +| Small Series | Short time frame for demand and pose to higher volatility | `OI01` | +| Extraordinary Demand | Temporary demand on top of standard demand. Used e.g. in the following scenarios:
    - logistic optimization (e.g., full use of container)
    - preventing shortage by building stock (banking)
    - restocking safety stock | `ED01` | +| Phase-Out-Period | Ramp down; Product or material retires from the market | `PO01` | + +*Table 4: Short-Term Material Demand categories* + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +> `urn:samm:io.catenax.short_term_material_demand:1.0.0` + +This identifier **MUST** be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The RDF turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating +additional file formats and serializations. It can be found under the following link: + +> [https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.short_term_material_demand/1.0.0/ShortTermMaterialDemand.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.short_term_material_demand/1.0.0/ShortTermMaterialDemand.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema **MUST** be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation *"GetSubmodel"*. + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to [[SMT]](#62-non-normative-reference). + +## 4 APPLICATION PROGRAMMING INTERFACES + +### 4.1 API USED TO EXCHANGE "SHORT-TERM MATERIAL DEMAND" INFORMATION + +As described in [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids) this standard builds upon the [[CX-0002]](#61-normative-references) Digital Twins in Catena-X +and [[CX-0126]](#61-normative-references) Industry Core Part Type standards. Therefore, the APIs provided by the Digital Twin +standard are combined with the part identification defined in the Industry Core standard. This chapter +defines how the aforementioned standards and the [[CX-0018]](#61-normative-references) +standard **MUST** be used to facilitate the provisioning of *Short-Term Material Demand* data. The +usage of the Discovery Services defined in [[CX-0001]](#61-normative-references), [[CX-0053]](#61-normative-references) is not mandatory, +because this standard assumes an already existing business relationship between the involved parties. + +The sequence diagram in *Figure 3* provides an overview of the interactions required to register the +Part Type Twin following the shared asset approach. + +- Steps 1 & 2: Register the dDTR access for the partner at the connector +- Steps 3 & 4: When using the repository pattern, create the submodel (and twin) +- Steps 5 & 6: Register the submodel endpoint for the partner at the connector +- Steps 7 & 8: Register or update the twin Shell Descriptor relying on the registered Connector asset + for the submodel endpoint and the identification data of the partners. + +> ***Note:*** This sequence diagram is simplified and does not cover the generation of the Part Type Twin +on supplier side and the handling of the identification data needed. Both partners need to create a +Part Type Twin of the shared asset as well as provide *Short-Term Material Demand* data. + +![Figure 3: Flow to create and register a digital twin](./assets/Figure_3.svg) +*Figure 3: Flow to create and register a digital twin* + +The sequence diagram in Figure 4 provides an overview of the interactions required when a customer +(acting as data provider) provisions *Short-Term Material Demand* data to a supplier (acting as data consumer). + +The flow "*Supplier reads (updated) Submodel from Customer*" visualizes the sequence of calls when consuming data: + +- Steps 3 - 8: Contract dDTR usage in the connector. +- Steps 9 - 12: Lookup the Industry Core Part Type Twin for a Part Type based on the common identification data. +- Steps 13 - 18: Read the Shell Descriptor of the Industry Core Part Type Twin to extract the *Short-Term Material Demand* + submodel endpoint (registered at the connector). +- Steps 19 - 24: Contract the *Short-Term Material Demand* data usage in the connector. +- Steps 25 - 29: Consume and use the *Short-Term Material Demand* data. + +![Figure 4: Flow to lookup a digital twin and get a submodel.](./assets/Figure_4.svg) +*Figure 4: Flow to lookup a digital twin and get a submodel.* + +> ***Note:*** Depending on the use of repository patterns and the design of the Digital Twins, the data +may be updated manually in the Submodel endpoint. + +#### 4.1.1 CONNECTOR DATA ASSET STRUCTURE + +The endpoints for the dDTR and the Submodel Endpoint **MUST** be made available BUT they **MUST NOT** +be directly called data consumer. Rather, for access to dDTRs and Submodels, there **MUST** be contracts +negotiated in accordance with the DSP. Therefore, the endpoints **MUST** be offered as connector data +assets. To make these assets easily identifiable in the connector's catalog, each asset **MUST** be +configured with a set of properties as described in the corresponding sections below. + +The following table provides an overview of the connector data assets that the parties **MUST** offer +to be able to provision and/or consume *Short-Term Material Demand* data. + +| **Party** | **REQUIRED** | **Asset** | **Purpose** | +| --- | --- | --- | --- | +| Customer | Yes | "Digital Twin Registry" | Allows a consumer to query for Part Type Twins and their *Short-Term Material Demand* submodels. | +| Customer | Yes | "Submodel Short-Term Material Demand" | Allows a consumer to read actual *Short-Term Material Demand* data related to a Part Type Twin. | +| Supplier | Yes | "Digital Twin Registry" | Allows a consumer to query for Part Type Twins and their *Short-Term Material Demand* submodels. | + +*Table 5: Connector data assets* + +In the sections below the asset definitions of the two different kinds of assets are defined. + +##### CONNECTOR DATA ASSET STRUCTURE FOR "Digital Twin Registry" + +To allow partners to find the "Short-Term Material Demand" data for a specific Industry Core Part Type Twin, +the provider **MUST** register a connector data asset (see details in [[CX-0018]](#61-normative-references)) specifying the address +of the Digital Twin Registry of the provider (see [[CX-0002]](#61-normative-references)). + +The data asset **MUST** be configured with the set of properties as defined in the table below. + +| **Object** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***@id*** | Identifier of the asset | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. | +| properties | [**http://purl.org/dc/terms/type**](http://purl.org/dc/terms/type) | Defines the "Digital Twin Registry" according to the Catena-X taxonomy. | **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#DigitalTwinRegistry"}` to allow filtering the data assets catalog for the respective "Digital Twin Registry". | +| properties | [**https://w3id.org/catenax/ontology/common#version**](https://w3id.org/catenax/ontology/common#version) | The version of the standard defining the implemented API of the "Digital Twin Registry" | **MUST** correspond to the version of the standard defining the Interfaces of the "Digital Twin Registry". The value **MUST** be set to `"3.0"` for "Digital Twin Registries" used by this standard. | +| dataAddress | **@type** | Type of the DataAddress node. | **MUST** be set to `"DataAddress"`. | +| dataAddress | ***baseUrl*** | Defines the HTTPS endpoint of the corresponding "Digital Twin Registry Endpoint". | The `{{ DIGITAL_TWIN_REGISTRY_ENDPOINT }}` refers to an URL under which the API of the "Digital Twin Registry" endpoint is available. HTTPS transport protocol **MUST** be used. | +| dataAddress | ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body | **SHOULD** be set to `"false"` to not allow the API endpoint to receive a HTTPS body via the HTTPS request. | +| dataAddress | ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method | **SHOULD** be set to `"false"` to only allow the API endpoint to receive GET requests. | +| dataAddress | ***proxyPath*** | Defines whether the endpoint allows to proxy paths for the URL | **MUST** be set to `"true"` to allow the API endpoint to receive appended paths of the HTTPS request. | +| dataAddress | ***type*** | Defines the type of data plane extension handling the data exchange | **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. | + +*Table 6: Connector data assets request properties* + +Additionally security identification information **MAY** be added to secure the "Decentralized Digital Twin Registry". + +When searching the Catalog of a provider, a consumer **SHOULD** use the following properties AND +their values to identify the Data Asset specifying "Digital Twin Registry". In the connector Data Asset +descriptions the API version valid for this standard is mentioned for the property +[`https://w3id.org/catenax/ontology/common#version`](https://w3id.org/catenax/ontology/common#version). The requester of a Data Asset **MUST** be +able to handle multiple Data Asset for this endpoint, being differentiated only by the version. +The requester **SHOULD** choose the Data Asset set with the highest compatible version number implemented +by themselves. If the requester cannot find a compatible version with their own, the requester **MUST** +terminate the data transfer. + +| **Property** | **Value** | +| --- | --- | +| http://purl.org/dc/terms/type | `{"@id": "https://w3id.org/catenax/taxonomy#DigitalTwinRegistry"}` | + +*Table 7: Connector data assets request properties values.* + +An example connector data asset definition is given below. + +>**Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "http://purl.org/dc/terms/" + }, + "@id": "{{CONNECTOR_ASSET_ID}}", + "properties": { + "dct:type": {"@id": "cx-taxo:DigitalTwinRegistry"}, + "cx-common:version": "3.0" + }, + "privateProperties": { + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ DIGITAL_TWIN_REGISTRY_ENDPOINT }}", + "proxyQueryParams": "true", + "proxyBody": "false", + "proxyPath": "true", + "proxyMethod": "false", + } +} +``` + +##### CONNECTOR DATA ASSET STRUCTURE FOR "Submodel" + +To allow partners to receive the "Short-Term Material Demand" data as defined in [Chapter 3](#3-aspect-models), +the provider **MUST** register a connector data asset (see details in[[ CX-0018]](#61-normative-references)) specifying the +address of the submodel endpoint (see [[CX-0002]](#61-normative-references)) providing the actual data. + +The data asset **MUST** be configured with the set of properties as defined in the table below. + +| **Object** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***@id*** | Identifier of the asset | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. | +| properties | [**http://purl.org/dc/terms/type**](https://purl.org/dc/terms/type) | Defines the "Submodel API" according to the Catena-X taxonomy. | **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#Submodel"}` to allow filtering the data assets catalog for the respective "Submodel API". | +| properties | [**https://admin-shell.io/aas/3/0/HasSemantics/semanticId**](https://admin-shell.io/aas/3/0/HasSemantics/semanticId) | The semantic identifier of the "Short-Term Material Demand" SAMM. | **MUST** be set to `{"@id": "urn:samm:io.catenax.short_term_material_demand:1.0.0#ShortTermMaterialDemand"}` to externally define how the Submodel must be interpreted. **MUST NOT** be set, if different submodels may be returned by this API. | +| properties | [**https://w3id.org/catenax/ontology/common#version**](https://w3id.org/catenax/ontology/common#version) | Version of the Submodel Interface Specification | **MUST** be set to `"3.0"` in accordance to [[CX-0002]](#61-normative-references). | +| dataAddress | **@type** | Type of the DataAddress node. | **MUST** be set to `"DataAddress"`. | +| dataAddress | ***baseUrl*** | Defines the HTTPS Submodel endpoint provisioning the *Short-Term Material Demand* data | The `{{ SUBMODEL_ENDPOINT }}` refers to an URL under which the Submodel API Endpoint ([[CX-0002]](#61-normative-references)) is available to provide the "Short-Term Material Demand" . HTTPS transport protocol **MUST** be used. | +| dataAddress | ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body | **SHOULD** be set to `"false"` to not allow the API endpoint to receive a HTTPS body via the HTTPS request. | +| dataAddress | ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method | **SHOULD** be set to `"false"` to only allow the API endpoint to receive GET requests. | +| dataAddress | ***proxyPath*** | Defines whether the endpoint allows to proxy paths for the URL | **MUST** be set to `"true"` to allow the API endpoint to receive appended paths of the HTTPS request. Setting this parameter depends on the implementation of the submodel lookup. | +| dataAddress | ***type*** | Defines the type of data plane extension handling the data exchange | **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. | + +*Table 8: Connector data assets request properties* + +Additionally security identification information **MAY** be added to secure the "Submodel API". + +When searching the data assets catalog of a provider, a consumer **SHOULD** use the `assetId` previously +determined via `subprotocolBody` of the SubmodelDescriptor's endpoint definition of subprotocol type "DSP". +Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for the definition of the `subprotocolBody`. + +| **Property** | **Value** | +| --- | --- | +| [https://w3id.org/edc/v0.0.1/ns/id](https://w3id.org/edc/v0.0.1/ns/id) | `{{CONNECTOR_ASSET_ID}}` specified in the DSP endpoint of the SubmodelDescriptor (see [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition)) | + +*Table 9: Connector data assets request properties values* + +An example connector data asset definition is given below. + +>**Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "http://purl.org/dc/terms/", + "aas-semantics": "https://admin-shell.io/aas/3/0/HasSemantics/" + }, + "@id": "{{CONNECTOR_ASSET_ID}}", + "properties": { + "dct:type": {"@id": "cx-taxo:Submodel"}, + "cx-common:version": "3.0", + "aas-semantics:semanticId": {"@id": "urn:samm:io.catenax.short_term_material_demand:1.0.0#ShortTermMaterialDemand"} + }, + "privateProperties": { + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ SUBMODEL_ENDPOINT }}", + "proxyQueryParams": "false", + "proxyBody": "false", + "proxyPath": "true", + "proxyMethod": "false", + } +} +``` + +#### 4.1.2 INDUSTRY CORE PART TYPE TWIN REGISTRATION AND DEFINITION + +##### 4.1.2.1 SHELL DESCRIPTOR REGISTRATION + +To allow partners to receive the actual "*Short-Term Material Demand*" data as defined in [Chapter 3](#3-aspect-models), +the provider **MUST** register a Shell Descriptor in the dDTR (see [[CX-0002]](#61-normative-references)) so that a partner: + +- May lookup the Industry Core Part Type Twin based on known identification data. +- May identify the connector endpoint providing access to the "Short-Term Material Demand" submodel data. + +The Shell Descriptors represent each an Industry Core Part Type Twin and **MUST** follow the rules as defined +in [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids). + +The Shell Descriptor **MUST** be configured with the set of properties as defined in the table below. + +| **Object in ShellDescriptor** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***id*** | Defines the technical ID of the Asset Administration Shell representing a partner's twin. | **MUST** be unique following Industry Core Part Type standard ([[CX-0126]](#61-normative-references)) and is a technical Id randomly assigned as multiple Part Type Twins may be created for one Part Type. E.g. this number differs for the twins created at supplier and customer side. | +| | ***globalAssetId*** | Defines the Catena-X ID of the twin. | **MUST** be aligned with the partner's material. When referring to the same Part Type Twin, the same number **MUST** be used (see [[CX-0126]](#61-normative-references)). | +| | **specificAssetIds** | Identifiers that may be used to lookup Part Type Twins. | **MUST** be set to according to the Industry Core Part Type standard ([[CX-0126]](#61-normative-references)). See *Table 11* for respective specific asset IDs. The `"customerPartId"` **MUST** be set by Customers and **SHOULD** be set by Suppliers. | +| submodelDescriptor | **id** | Technical identifier of a SubmodelDescriptor. | **MUST** be set to a unique identifier. | +| submodelDescriptor | **semanticId** | The semantic identifier of the "Short-Term Material Demand" SAMM. | **MUST** be set to `{ "type": "ExternalReference", "keys": [{ "type": "GlobalReference", "value": "urn:samm:io.catenax.short_term_material_demand:1.0.0#ShortTermMaterialDemand" }] }` to externally define how the Submodel must be interpreted. | +| submodelDescriptor > endpoint | **interface** | Defines the Submodel Interface [[CX-0002]](#61-normative-references) and the version. | **MUST** be set to `"SUBMODEL-3.0"` to rely on current specification. | +| submodelDescriptor > endpoint > protocolInformation | **href** | Defines the direct link to the public API of the connector's data plane with a path that **SHOULD** be appended by the proxy, if needed. | **MUST** be set to the public API of the data plane providing the data with the path appended to directly access the submodel. | +| submodelDescriptor > endpoint > protocolInformation | **subprotocol** | Defines the usage of the connector based on DSP to access and use the submodel. | **MUST** be set to `"DSP"` to define the connector endpoint of the subprotocol. | +| submodelDescriptor > endpoint > protocolInformation | **subprotocolBody** | Defines the asset id in the connector and the connector address to access and use the submodel. | **MUST** be set to `"id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}"` to provide the necessary information for contracting the submodel endpoint. Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for the definition of the asset of the subprotocolBody. | + +*Table 10: Properties relevant for the Shell Descriptor definition* + +When searching the submodel in the dDTR of a provider, a consumer **SHOULD** use the specific asset IDs +as defined in [[CX-0126]](#61-normative-references). Table 11 gives an overview of the specific asset IDs that the data provider +added to the ShellDescriptor so that the data consumer may find the Industry Core Part Type Twin. + +| **Specific Asset Id** | **Value** | +| --- | --- | +| digitalTwinType | "PartType". Set to identify twins compliant to the Industry Core Part Type (see [[CX-0126]](#61-normative-references)). | +| manufacturerId | Supplier / Manufacturer partner BPNL (see [[CX-0010]](#61-normative-references)) | +| manufacturerPartId | Supplier / Manufacturer partner identification number of the part. | +| customerPartId | Customer partner identification number of the part. | + +*Table 11: Specific asset IDs of Industry Core Part Type Twins proposed to be used to look up a twin in the dDTR* + +The Shell Descriptor defines the metadata of the Industry Core Part Type Twin. The following example +presents a Shell Descriptor of a customer providing two of its suppliers access to a "Short-Term Material Demand" +submodel. For further information on the creation of Part Type Twins, refer to [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids). + +Following [[CX-0002]](#61-normative-references), when searching the data assets catalog of a provider, a consumer **SHOULD** +use the `assetId` determined via `subprotocolBody` of the SubmodelDescriptor's endpoint definition +of subprotocol type `"DSP"` of the Submodel Descriptor of interest. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "id": "{{TECHNICAL_TWIN_ID}}", + "globalAssetId": "{{MATERIAL_NUMBER_CX}}", + "idShort": "Semiconductor", + "specificAssetIds": [ + { + "name": "digitalTwinType", + "value": "PartType", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "manufacturerPartId", + "value": "{{MATERIAL_NUMBER_SUPPLIER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "manufacturerId", + "value": "{{SUPPLIER_BPNL}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "customerPartId", + "value": "{{MATERIAL_NUMBER_CUSTOMER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + } + ] + } + } + ], + "submodelDescriptors": [ + { + "id": "e5c96ab5-896a-482c-8761-efd74777ca97", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.short_term_material_demand:1.0.0#ShortTermMaterialDemand" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "{{SUPPLIER_CONNECTOR_DATAPLANE_PUBLIC_API}}/{{PATH_IF_NEEDED}}", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ] + } + ] +} +``` + +##### 4.1.2.2 LOOKING UP A PART TYPE TWIN IN THE DDTR + +To query the dDTR of a data provider, after contracting the usage via the data provider's connector +(see [[CX-0018]](#61-normative-references)), the lookup API (see [[CX-0002]](#61-normative-references)) can be used relying on the specific +asset IDs defined by the Industry Core Part Type (see [[CX-0126]](#61-normative-references)) that can be seen in +Table 11 (table of shellDescriptorRegistration with specific asset IDs). + +An example call relying on all information is given in the code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{PARTNER_CONNECTOR_DATA_PLANE}}/lookup/shells?assetIds={"name":"digitalTwinType", "value": "PartType"},{"name":"manufacturerPartId", "value": "{{MATERIAL_NUMBER_SUPPLIER}}"},{"name":"manufacturerId", "value": "{{SUPPLIER_BPNL}}"},{"name":"customerPartId", "value": "{{MATERIAL_NUMBER_CUSTOMER}}"} +``` + +As a result identifiers of the ShellDescriptors will be returned. With this data, a data provider can +read the ShellDescriptor to extract the endpoint data of the data provider. An example is given in the +code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{PARTNER_CONNECTOR_DATA_PLANE}}/shell-descriptors/{{AAS_IDENTIFIER}} +``` + +##### 4.1.2.3 FETCHING SUBMODEL DATA + +To fetch the *Short-Term Material Demand* Submodel data at the submodel endpoint of a data provider, after +contracting the usage via the data provider's connector (see [[CX-0018]](#61-normative-references)), the submodel API (see [[CX-0002]](#61-normative-references)) +can be used. + +An example call relying on all information is given in the code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{HREF_PATH}}/$value +``` + +## 5 PROCESSES + +> *This section is normative* + +The *Short-Term Material Demand* is intended to provide more details and insights about the +customer's demand. It is not meant to replace regular and legally binding orders or call-offs +between partners but to offer supplementary information. Therefore the *Short-Term Material +Demand* aspect model provides several categories that may be used to differentiate between +different types of demand. The categories originate from the joint use of the aspect model of the +Demand and Capacity Standard [[CX-0128]](#61-normative-references) and may not necessarily apply. Categories should only +be used if they are beneficial for at least one of the partners involved. If in doubt, "Default" **SHOULD** +always be used. + +The key purpose of the *Short-Term Material Demand* is to indicate the actual required quantities +that are critical for the customer's planned production. To do so it is **RECOMMENDED** to use the +Categories "Default" or "Series". Quantities deviating from this, e.g. to build up stock or to +optimize logistics, **SHOULD** be mapped to "Extraordinary Demand". All other categories should be +selected and used after aligning with the respective partner to ensure a mutual understanding and +intention of use. + +The following chapter should contribute to the understanding by providing different process +representations and examples. + +### 5.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Supplier** | The supplier acts as the data consumer in this standard. | Is a business partner that supplies items to a customer. As such, a supplier is interested in detailed information about the customer's *Short-Term Material Demand*. | +| **Customer** | The customer acts as the data provider in this standard. | Is a business partner that procures items from suppliers and provides information about his *Short-Term Material Demand.* | + +*Table 12: Actors and roles* + +### 5.2 PROCESS REPRESENTATIONS + +#### 5.2.1 SINGLE SOURCING USING A SINGLE CATEGORY + +In this most basic example the customer procures materials from a single supplier to fulfill its +demands for a specific material. Also the call-off or order quantities exactly match the quantities +that are required for the customer's production on a daily basis. + +The following table visualizes the data which may be transferred as *Short-Term Material Demand*. + +![Table 13: Single sourcing with one demand category and daily ordering](./assets/Table_13.svg) +*Table 13: Single sourcing with one demand category and daily ordering* + +Another scenario in this context might be that the delivery date stated in the call-off or order +does not match the actual expected consumption date for the material. + +![Table 14: Single sourcing with one demand category and non-daily ordering](./assets/Table_14.svg) +*Table 14: Single sourcing with one demand category and non-daily ordering* + +The additional information can be e.g. used to smooth out the supplier's production and to jointly +agree between partners on a split of the total order quantity across different delivery days. The +same applies for a shortage case where the supplier is not able to deliver the ordered quantity on +day 1. + +#### 5.2.2 SINGLE SOURCING USING MULTIPLE CATEGORIES + +Additional information about the customer's *Short-Term Material Demand* can be provided via +categories. The following example shows a scenario where the customer is signaling that the ordered +amount of material on *day 2* is partially intended to build up safety stock and is not directly +related to a planned consumption. + +![Table 15: Single sourcing with multiple demand categories to signal stock building](./assets/Table_15.svg) +*Table 15: Single sourcing with multiple demand categories to signal stock building* + +With this additional information the supplier can distinguish which quantity is the absolute minimum +required to fulfill the customer's production needs and which is e.g., to build up a safety stock +or to replenish stock. In the event of a production bottleneck, the supplier can suggest stretching +the delivery of the additional parts. The supplier is also informed that this is not a regular +increase in demand, which in turn can be used while communicating with its upstream suppliers and +may therefore contribute to reduce the bullwhip effect. + +In the same manner, the customer can make use of the categories e.g., to indicate that a partial +quantity is attributed to logistical optimizations. This might be e.g. due to fixed container sizes. +The following example shows a scenario in which one container always carries a batch of 15 pieces. + +![Table 16: Single sourcing with multiple demand categories to distinguish quantities for logistical optimizations](./assets/Table_16.svg) +*Table 16: Single sourcing with multiple demand categories to distinguish quantities for logistical optimizations* + +#### 5.2.3 MULTI-SOURCING WITH MULTIPLE CATEGORIES + +A multi-sourcing strategy is a common approach in supply chain management to mitigate supply risks. +This means that a customer works with two or more suppliers to procure equivalent materials. +However, to use the "Short-Term Material Demand Exchange" standard, participants must comply with +legal restrictions, such as competition laws. Furthermore, it is in the interests of the customer +not to disclose any company secrets about existing business relationships and their extent with +third parties. + +Therefore, in case of multi-sourcing, each participant needs to prevent potential prohibited or +disadvantageous data leakage during the information provisioning. Any *Short-Term Material Demand* +provided must be partner-specific. In case of multi-sourcing the demand data can be e.g., broken +down based on the partner's proportion of the customer's total demand volume. Using +supplier-specific material numbers may support the data provisioning system-wise. + +In the following example a customer has two suppliers, that are sourced 60% and 40% respectively. +Therefore demands need to be split according to the given quota. In addition to the demand directly +derived from the customer's material consumption, the customer orders additional material on Day 1 +and Day 2 to build up a safety stock. + +![Table 17: Multi-sourcing with multiple demand categories to signal stock building](./assets/Table_17.svg) +*Table 17: Multi-sourcing with multiple demand categories to signal stock building* + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [CX-0001] | EDC Discovery API | 1.0.2 | +| [CX-0002] | Digital Twins in Catena-X | 2.2.0 | +| [CX-0003] | SAMM Aspect Meta Model | 1.1.0 | +| [CX-0006] | Registration and initial onboarding | 2.0.0 | +| [CX-0010] | Business Partner Number (BPN) | 2.0.0 | +| [CX-0018] | Dataspace Connectivity | 3.0.0 | +| [CX-0053] | Discovery Finder and BPN Discovery Service APIs | 1.1.0 | +| [CX-0118] | Delivery Information Exchange | 2.0.0 | +| [CX-0121] | Planned Production Output Exchange | 2.0.0 | +| [CX-0122] | Item Stock Exchange | 2.0.0 | +| [CX-0126] | Industry Core Part Type | 2.0.0 | +| [CX-0128] | Demand and Capacity Management | 2.0.0 | +| [CX-0145] | Days of Supply Exchange | 1.0.0 | +| [CX-0146] | Supply Chain Disruption Notifications | 1.0.0 | + +### 6.2 NON-NORMATIVE REFERENCE + +> *This section is non-normative* + +| **Context** | **Link** | +| --- | --- | +| [CX-OMW] | Catena-X Operating Model Whitepaper. Download from: [https://catena-x.net/fileadmin/\_online\_media\_/CX\_Operating\_Modelv2.1_final.pdf](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf) | +| [CX-ODRL] | Catena-X ODRL Profile repository: https://github.com/catenax-eV/cx-odrl-profile | +| [RFC2119] | Bradner, S. Key words for use in RFCs to Indicate Requirement Levels. Available online: https://datatracker.ietf.org/doc/html/rfc2119 | +| [RFC8174] | Leiba, B. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. Available online: https://datatracker.ietf.org/doc/html/rfc8174 | +| [SMT] | How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf | +| [IDTA-01002-3-0] | Specification of the Asset Administration Shell Part 2: Application Programming Interfaces. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API.pdf | + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_1.svg b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_1.svg new file mode 100644 index 000000000..8f48f1725 --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_1.svg @@ -0,0 +1,4 @@ + + + +
    Data Provider
    Data Provider
    Connector
    Connector
    Busines Application
    Busines App...
    Catena-X Core Service Provider
    Catena-X Core Service Provider
    IAM
    IAM
    Credential Service
    Credential S...
    Keycloak
    Keycloak
    Data Consumer
    Data Consumer
    Connector
    Connector
    Busines Application
    Busines Applicati...
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
    (8) Get Submodel
    (8) Get Su...
    (5) Query dDTR for Twin and submodel
    (5) Query dDTR for Twin and submodel
    (4) Connector Communication
      (Catalog / Contracting / Transfer)  
    (4) Connector Communication...
    dDTR
    dDTR
    Submodel Endpoint
    Submodel E...
    (10) Get Submodel
    (10) Get S...
    (3) Register Twin
    with Submodels
    (3) Register Twin...
    (2) Register Submodel Endpoint
     at Connector
    (2) Register Submodel Endpoint...
    (9)
    (9)
    Text
    Text
    (6) Get lookup/shells
    by specific asset ids
    (6) Get lookup/shells...
    (1) Register dDTR at Connector
    (1) Register dDTR at Connector
    (7) Get shell-descriptors
    by AAS ID
    (7) Get shell-descriptors...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_2.svg b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_2.svg new file mode 100644 index 000000000..4d0cc023b --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_2.svg @@ -0,0 +1,4 @@ + + + +
    represents same material
    equivalent specific asset IDs, global asset ID,
    different AAS ID
    represents same material...
    PartType for Material (e.g. "Semiconductor")
    PartType for Material...
    Supplier
    Supplier
    Customer
    Custom...
    Asset
    registered in dDTR as AAS
    Asset...
    Submodel
    Submodel
    PartType for Material "Control Unit"
    PartType for Materia...
    ShortTerm
    MaterialDemand
    ShortTerm...
    PartTypeInformation
    PartTypeInformation
    SingleLevelUsageAs Planned
    SingleLevelUsageAs P...
    submodel of
    submodel of
    submodel of
    submodel of
    references twin
    references twin
    PartTypeInformation
    PartTypeInformation
    SingleLevel
    BomAsPlanned
    SingleLevel...
    references twin
    references twin
    submodel of
    submodel of
    submodel of
    submodel of
     Legend
     Legend
    Digital Twin in DTR
    Digital Twin in DTR
    Submodel (CX-0120)
    Submodel (CX-0120)
    Submodel (IC Part Type)
    Submodel (IC Part Type)
    submodel of
    submodel of
    references twin
    references twin
    PartType for Material "Semiconductor"
    PartType for Materia...
    submodel of
    submodel of    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_3.puml b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_3.puml new file mode 100644 index 000000000..f46a51236 --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_3.puml @@ -0,0 +1,43 @@ +@startuml Figure_3 +title Shared Digital Approach - Registration of IC Part Type Twin + +autonumber + +box "Supplier" #LightBlue + participant SupplierApplication as "Application" + participant SupplierDTR as "dDTR" + participant SupplierSubmodelEndpoint as "Submodel Endpoint" + participant SupplierEDC as "Connector" +end box + +box "Customer" #LightGreen + participant CustomerEDC as "Connector" + participant CustomerSubmodelEndpoint as "Submodel Endpoint" + participant CustomerDTR as "dDTR" + participant CustomerApplication as "Application" +end box + +== Supplier registers IC Part Type Twin with Submodel for Customer == + + note over SupplierApplication, SupplierSubmodelEndpoint: Supplier created Part Type Twin + + +== Customer registers IC Part Type Twin with Submodel for Supplier == + CustomerApplication -> CustomerEDC: Register dDTR for partner at Connector + activate CustomerEDC + return OK + + note over CustomerSubmodelEndpoint, CustomerApplication: Keeping Submodel updated only needed\nfor repository pattern + CustomerApplication -> CustomerSubmodelEndpoint: Create Submodel + activate CustomerSubmodelEndpoint + return OK + + CustomerApplication -> CustomerEDC: Register endpoint of Submodel for READ access for partner at Connector + activate CustomerEDC + return OK + + CustomerApplication -> CustomerDTR: Register IC Part Type Twin Shell Descriptor\n with Submodel endpoint\nfor Partner in dDTR\n(DSP endpoint) + activate CustomerDTR + return OK + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_3.svg b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_3.svg new file mode 100644 index 000000000..7372884ad --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_3.svg @@ -0,0 +1,53 @@ +Shared Digital Approach - Registration of IC Part Type TwinSupplierCustomerApplicationApplicationdDTRdDTRSubmodel EndpointSubmodel EndpointConnectorConnectorConnectorConnectorSubmodel EndpointSubmodel EndpointdDTRdDTRApplicationApplicationSupplier registers IC Part Type Twin with Submodel for CustomerSupplier created Part Type TwinCustomer registers IC Part Type Twin with Submodel for Supplier1Register dDTR for partner at Connector2OKKeeping Submodel updated only neededfor repository pattern3Create Submodel4OK5Register endpoint of Submodel for READ access for partner at Connector6OK7Register IC Part Type Twin Shell Descriptorwith Submodel endpointfor Partner in dDTR(DSP endpoint)8OK \ No newline at end of file diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_4.puml b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_4.puml new file mode 100644 index 000000000..e42c97417 --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_4.puml @@ -0,0 +1,84 @@ +@startuml Figure_4 +title Shared Digital Twin Approach - Lookup of IC Part Type Twin + +autonumber + +box "Supplier" #LightBlue + participant SupplierApplication as "Application" + participant SupplierDTR as "dDTR" + participant SupplierSubmodelEndpoint as "Submodel Endpoint" + participant SupplierEDC as "Connector" +end box + +box "Customer" #LightGreen + participant CustomerEDC as "Connector" + participant CustomerSubmodelEndpoint as "Submodel Endpoint" + participant CustomerDTR as "dDTR" + participant CustomerApplication as "Application" +end box + + +== Customer updates Submodel information (repository pattern only) == + note over CustomerSubmodelEndpoint, CustomerApplication: Keeping Submodel updated only needed\nfor repository pattern + CustomerApplication -> CustomerSubmodelEndpoint: Update Submodel information + activate CustomerSubmodelEndpoint + return OK + + +== Supplier reads (updated) Submodel from Customer == + + SupplierApplication -> SupplierEDC: Query Connector Catalog for Customer dDTR access + activate SupplierEDC + + SupplierEDC <-> CustomerEDC: DSP communication + + return Catalog + + SupplierApplication -> SupplierEDC: Negotiate Contract and init transfer + activate SupplierEDC + SupplierEDC <-> CustomerEDC: DSP communication + return OK + + SupplierApplication -> CustomerEDC: Query DTR for IC Part Type Twin based on specific asset ids + activate CustomerEDC + CustomerEDC -> CustomerDTR: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerDTR + CustomerDTR --> CustomerEDC + deactivate CustomerDTR + return ShellDescriptor Ids + + SupplierApplication -> SupplierApplication: select ShellDescriptor ID\nto get ShellDescriptor for\nIC PartType Twin + + SupplierApplication -> CustomerEDC: Lookup IC Part Type Twin based on ShellDescriptor Id + activate CustomerEDC + CustomerEDC -> CustomerDTR: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerDTR + CustomerDTR --> CustomerEDC + deactivate CustomerDTR + return ShellDescriptor + + SupplierApplication -> SupplierApplication: Extract DSP Endpoint and Connector Asset ID for Submodel + + SupplierApplication -> SupplierEDC: Query Connector Catalog for Submodel based on Connector Asset ID + activate SupplierEDC + + SupplierEDC <-> CustomerEDC: DSP communication + + return Catalog + + SupplierApplication -> SupplierEDC: Negotiate Contract for Submodel and init transfer + activate SupplierEDC + SupplierEDC <-> CustomerEDC: DSP communication + return OK + + SupplierApplication -> CustomerEDC: Read Submodel + activate CustomerEDC + CustomerEDC -> CustomerSubmodelEndpoint: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerSubmodelEndpoint + CustomerSubmodelEndpoint --> CustomerEDC + deactivate CustomerSubmodelEndpoint + return Submodel + + SupplierApplication -> SupplierApplication: Use Submodel + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_4.svg b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_4.svg new file mode 100644 index 000000000..fa3889e45 --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Figure_4.svg @@ -0,0 +1,94 @@ +Shared Digital Twin Approach - Lookup of IC Part Type TwinSupplierCustomerApplicationApplicationdDTRdDTRSubmodel EndpointSubmodel EndpointConnectorConnectorConnectorConnectorSubmodel EndpointSubmodel EndpointdDTRdDTRApplicationApplicationCustomer updates Submodel information (repository pattern only)Keeping Submodel updated only neededfor repository pattern1Update Submodel information2OKSupplier reads (updated) Submodel from Customer3Query Connector Catalog for Customer dDTR access4DSP communication5Catalog6Negotiate Contract and init transfer7DSP communication8OK9Query DTR for IC Part Type Twin based on specific asset ids10forward request based on Connector asset definitions(consumer proxy)11 12ShellDescriptor Ids13select ShellDescriptor IDto get ShellDescriptor forIC PartType Twin14Lookup IC Part Type Twin based on ShellDescriptor Id15forward request based on Connector asset definitions(consumer proxy)16 17ShellDescriptor18Extract DSP Endpoint and Connector Asset ID for Submodel19Query Connector Catalog for Submodel based on Connector Asset ID20DSP communication21Catalog22Negotiate Contract for Submodel and init transfer23DSP communication24OK25Read Submodel26forward request based on Connector asset definitions(consumer proxy)27 28Submodel29Use Submodel \ No newline at end of file diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_13.svg b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_13.svg new file mode 100644 index 000000000..6c86bc43c --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_13.svg @@ -0,0 +1 @@ +Customer InformationDay 1Day 2Day 3Day 4Consumption in production8080100100Call-off / orderamount8080100100Demand category= Series / Default8080100100End of day Item Stock0000Transferable Short-Term Material Demand Information \ No newline at end of file diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_14.svg b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_14.svg new file mode 100644 index 000000000..b004fb18d --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_14.svg @@ -0,0 +1 @@ +Customer InformationDay 1Day 2Day 3Day 4Consumption in production8080100100Call-off / order amount360000Demand category= Series / Default8080100100End of day Item Stock2802001000Transferable Short-Term Material Demand Information \ No newline at end of file diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_15.svg b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_15.svg new file mode 100644 index 000000000..5d00551ad --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_15.svg @@ -0,0 +1 @@ +Customer InformationDay 1Day 2Day 3Day 4Consumption in production8080100100Call-off / order amount80200100100Demand category= Series / Default8080100100Demand category= ExtraordinaryDemand012000End of day Item Stock0120120120Transferable Short-Term Material Demand Information \ No newline at end of file diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_16.svg b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_16.svg new file mode 100644 index 000000000..d051009a1 --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_16.svg @@ -0,0 +1 @@ +Customer InformationDay 1Day 2Day 3Day 4Consumption in production8080100100Call-off / orderamount9075105105Demand category= Series / Default8080100100Demand category= ExtraordinaryDemand10055End of day Item Stock100510Transferable Short-Term Material Demand Information \ No newline at end of file diff --git a/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_17.svg b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_17.svg new file mode 100644 index 000000000..8c8aa8987 --- /dev/null +++ b/docs/standards/CX-0120-ShortTermMaterialDemandExchange/assets/Table_17.svg @@ -0,0 +1 @@ +Customer InformationDay 1Day 2Day 3Day 4Consumption in production8080100100Tosupplier#1 (60%)Call-off / orderamount60606060Demand category= Series / Default48486060Demand category= ExtraordinaryDemand121255To supplier#2 (40%)Call-off / orderamount404040400Demand category= Series / Default32324040Demand category= ExtraordinaryDemand8855End of day Item Stock20404040Transferable Short-Term Material Demand Information \ No newline at end of file diff --git a/docs/standards/CX-0121-PlannedProductionOutputExchange/CX-0121-PlannedProductionOutputExchange.md b/docs/standards/CX-0121-PlannedProductionOutputExchange/CX-0121-PlannedProductionOutputExchange.md new file mode 100644 index 000000000..ab96136d4 --- /dev/null +++ b/docs/standards/CX-0121-PlannedProductionOutputExchange/CX-0121-PlannedProductionOutputExchange.md @@ -0,0 +1,1033 @@ +# CX-0121 Planned Production Output Exchange 1.0.0 + +## ABSTRACT + +The supplier's *Planned Production Output* is one of the key determinants for avoiding a shortage at +the customer's site. With information about the supplier's *Planned Production Output* quantities +allocated to a specific customer, it can be monitored and predicted whether the customer demands can +be fully supplied. If this is not the case, the information can be used by the customer to derive +adequate countermeasures to keep the impact as low as possible. These measures can range, for +example, from creating an adapted production plan with the supplier, rescheduling or reducing the +customer's demand and production to, e.g. organizing an express delivery from an alternative supplier. + +However, collecting the *Planned Production Output* information manually e.g. by phone or e-mail is +error prone and slow. As a result, unmet demands often remain unnoticed for too long and +unnecessarily restrict the scope for countermeasures. This often leads to shortages, costly +fire-fighting measures in the supply chain, production interruptions and ultimately to customer +dissatisfaction. + +The standardization of the supplier's *Planned Production Output* semantics and exchange API enables +participants in the supply chain to share information about time-bound *Planned Production Output* +quantities at a supplier's site in an interoperable manner. + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +Changes: + +- integration and usage of digital twins as defined in [[CX-0002]](#61-normative-references) Digital Twins in Catena-X +- harmonization of aspect model in accordance with [[CX-0126]](#61-normative-references) Industry Core: Part Type +- discontinuation of the proprietary API used in v1.0.0 of this standard +- grammatical, spelling and semantic improvements + +New Content: + +- added a note on the obligation of standard implementers to make aware that sensitive data is being + handled, see [[Chapter 2.1.3]](#213-additional-requirements) + +## 1 INTRODUCTION + +In recent years global supply chains have been significantly affected by global crises. This is +compounded by ever-increasing complexity and interdependencies. As a result small and medium-sized +enterprises as well as large enterprises are exposed to an increased risk of disruptions in their +supply chains. To adapt to short-term fluctuations and develop the right countermeasures, it is +essential to have sound information about the *Planned Production Output* of their suppliers. + +This document describes and standardizes the semantic aspect model for the *Planned Production +Output* as well as the associated API to exchange *Planned Production Output* information between +supply chain partners. The supplier's *Planned Production Output* is the planned quantity of a +material allocated to a specific customer in a time horizon of up to four weeks, that has not yet +been produced. It has not yet been produced and is allocated to a specific partner. The scope of +application is limited to existing business relationships and build-to-order (BTO) scenarios. +Build-to-stock (BTS) use cases with no existing business relationships are explicitly not covered. +In contrast to the strategic Demand and Capacity Management standard (DCM) [[CX-0128]](#61-normative-references), the +*Planned Production Output* refers to short-term production planning, i.e. the actual utilization of +existing and available capacity that resulted from capacity planning. It shows the latest production +schedule-related information for a period of up to four weeks. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following roles defined in [[CX-OMW]](#62-non-normative-reference): + +- **Data Providers** willing to provide *Planned Production Output* data +- **Data Consumers** interested in requesting and receiving *Planned Production Output* data +- **Business Application Providers** interested in providing solutions implementing this standard +- **Consulting Services Providers** interested in supporting companies fulfilling the standard + +The scope of this standard is only the Planned Production Output aspect model and API. It describes +the exchange of Planned Production Output data through a connector in accordance to [[CX-0018]](#61-normative-references). + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +A typical order-based procurement process includes a customer who places an order and a supplier +fulfilling it. If the ordered material is not on stock in a sufficient quantity at a supplier's +facility (see [[CX-0122]](#61-normative-references) Item Stock Exchange) it needs to be scheduled for production. These +quantities of scheduled production are the subject of this standard and are referred to as the +*Planned Production Output*. To ensure that the *Planned Production Output* information will be +interpreted, handled and exchanged in an interoperable manner between partners participating in +Catena-X, this standard document defines the PlannedProductionOutput aspect model and the API to be +used in the Catena-X network. + +*Figure 1* shows the high-level architecture of the "Planned Production Output Exchange" in the +Catena-X dataspace and the services that are involved. Both the data consumer and the data provider +must be members of the Catena-X network in order to communicate with each other. With the help of +the Credential Service and the Identity Access Management (IAM) each participant can authenticate +itself, verify the identity of the requesting party and decide whether to authorize the request. +The *Planned Production Output* data is provisioned in accordance with [[CX-0002]](#61-normative-references). + +![Figure 1: high-level architecture of the Planned Production Output Exchange in Catena-X](./assets/Figure_1.svg) +*Figure 1: high-level architecture of the Planned Production Output Exchange in Catena-X* + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. The +keywords **MAY** , **MUST** , **MUST NOT** , **OPTIONAL** , **RECOMMENDED** , **REQUIRED** , +**SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in [BCP 14] +[[RFC2119]](#62-non-normative-reference) [[RFC8174]](#62-non-normative-reference) when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X +standards. To validate that the standards are applied correctly, Catena-X employs Conformity +Assessment Bodies (CABs). The proof of conformity for a single semantic model is done according to +the general rules for proving the conformity of data provided to a semantic model or the ability to +consume the corresponding data. Furthermore, participants agree to follow the normative language of +this standardization document and to implement the required API-Endpoints described in [Chapter 4](#4-application-programming-interface). + +### 1.4 EXAMPLES + + The following JSON provides an example of the value-only serialization of the "PlannedProductionOutput" + aspect model. It contains the *Planned Production Output* quantities for three consecutive days in two + different sites (BPNS). + +```json +{ + "materialGlobalAssetId":"urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df", + "positions":[ + { + "lastUpdatedOnDateTime":"2023-04-01T14:23:00+01:00", + "orderPositionReference": { + "supplierOrderId":"M-Nbr-4711", + "customerOrderId":"C-Nbr-4711", + "customerOrderPositionId":"PositionId-01" + }, + "allocatedPlannedProductionOutputs":[ + { + "plannedProductionQuantity":{ + "value": 10, + "unit":"unit:piece" + }, + "productionSiteBpns":"BPNS0123456789ZZ", + "estimatedTimeOfCompletion":"2023-04-01T14:23:00+01:00" + }, + + { + "plannedProductionQuantity":{ + "value":20, + "unit":"unit:piece" + }, + "productionSiteBpns":"BPNS0123456789YZ", + "estimatedTimeOfCompletion":"2023-04-02T14:23:00+01:00" + }, + + { + "plannedProductionQuantity":{ + "value": 10, + "unit":"unit:piece" + }, + "productionSiteBpns":"BPNS0123456789ZZ", + "estimatedTimeOfCompletion":"2023-04-03T14:23:00+01:00" + } + ] + } + ] +} +``` + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +| **Name** | **Abrv.** | **Description** | +| --- | --- | --- | +| **Business Partner Number** | BPN | A BPN is the unique identifier of a partner within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Business Partner Number Legal Entity** | BPNL | A BPNL is the unique identifier of a partner legal entity within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Business Partner Number Site** | BPNS | A BPNS is the unique identifier of a partner site within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Business Partner Number Address** | BPNA | A BPNA is the unique identifier of a partner address within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Position** | | A position within an order defines the product and the quantity the supplier has to manufacture / supply for a customer. A single order may contain multiple positions for different products. | +| **Order** | | Request from a customer towards a supplier to manufacture / supply a given quantity of a specific product in a predefined time frame. | +| **Allocated Stock** | | The already manufactured and not yet been used products, components or material. They are allocated to a specific customer based on the orders made by the latter and are either still in the supplier's warehouse or already in the customer's warehouse. | +| **Provider** | | The party providing the *Planned Production Output* data. In the context of the *Planned Production Output* exchange API this is the supplier. | +| **Consumer** | | The party requesting and consuming the *Planned Production Output* data provided by the provider. In the context of the *Planned Production Output* exchange API this is the customer. | +| **Stock Location** | | The physical location of a stock specified by its corresponding BPNS and BPNA. More information on BPN/S/A is provided in [CX-0010]. | +| **Customer** | | The recipient of products ordered from / manufactured by a supplier. | +| **Supplier** | | The supplier / manufacturer of a product. | +| **Stock** | | Two way direction of material on stock:
    - One can have a stock of material which is ready for delivery to customers.
    - One can have a stock of material which can be used for the own production. | +| **Material** | | The term material is used as a catalogue item in the meaning of the Industry Core Part Type ([[CX-0126]](#61-normative-references)). Whenever referring to material also products, components or items are considered. Semi-finished goods are not intended to be covered. | +| **Production Output** | | The output quantity in a defined period of time for a component or material. | +| **Digital Twin** | DT | Digital representation of an asset that provides data on aspects of the represented data following [[CX-0002]](#61-normative-references). | +| **decentralized Digital Twin Registry** | dDTR | Component providing registration and discovery API implementations following [[CX-0002]](#61-normative-references). Sometimes referred to without the "decentralized" BUT in Catena-X those are always decentralized. | +| **Asset Administration Shell** | AAS | Technical concept for Digital Twins consisting of different standards. Application in Catena-X is described in Digital Twins in Catena-X standard ([[CX-0002]](#61-normative-references)) | +| **Shell Descriptor** | | Technical concept of the AAS API describing metadata of an Asset Administration Shell representing a Digital Twin. It holds identification information and metadata about which submodels are available and where to get the data from (see [[CX-0002]](#61-normative-references), [[IDTA-01002-3-0]](#62-non-normative-reference)). There may exist multiple Shell Descriptor for the same represented Asset (see [[CX-0126]](#61-normative-references)). | +| **Submodel Descriptor** | | Technical concept of the AAS API describing metadata of Submodels within a Shell Descriptor (Asset Administration Shell) (see [[CX-0002]](#61-normative-references), [[IDTA-01002-3-0]](#62-non-normative-reference)). | +| **Specific Asset Ids** | | Identifiers of the Shell Descriptor (Asset Administration Shell) that refer to common identification data for an asset/material at hand e.g., manufacturer part Id. Common specific asset ids used for identification are described in Industry Core Part Type Standard (see [[CX-0126]](#61-normative-references)). | +| **Asset Administration Shell Identifier** | AAS ID | Also referred to as Shell Descriptor Id, is the technical identifier of the Shell Descriptor. | +| **Global Asset Id** | | Also referred to as Catena-X Id, is the Catena-X identifier for assets represented by Digital Twins (see [[CX-0126]](#61-normative-references)). | +| **Aspect** | | A domain-specific view on information and functionality associated with a specific Digital Twin with a reference to a concrete Aspect Model (see [[CX-0002]](#61-normative-references)). Within Catena-X, an aspect is formally described using the Semantic Aspect Meta Model (see [[CX-0003]](#61-normative-references)). | +| **Semantic Id** | | Identifier including namespace to specify the semantic description of submodels using the Semantic Aspect Meta Model (SAMM). It allows partners to know the exact data format and semantics when e.g., browsing catalogs (see [[CX-0003]](#61-normative-references)). | +| **Data Space Protocol** | DSP | A set of specifications designed to facilitate interoperable data sharing between entities governed by usage control and based on Web technologies. These specifications define the schemas and protocols required for entities to publish data, negotiate Agreements, and access data as part of a Dataspace. It is governed by the International Data Spaces Association. Connectors compliant to [[CX-0018]](#61-normative-references) support the Data Space Protocol. | + +*Table 1: Terminology Planned Production Output Standard* + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 Planned Production Output Exchange + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +The following Catena-X standards are prerequisites for the implementation of this standard and therefore +**MUST** be considered / implemented by the relevant parties specified in each of them. + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0001]](#61-normative-references) | EDC Discovery API | 1.0.2 | +| [[CX-0002]](#61-normative-references) | Digital Twins in Catena-X | 2.2.0 | +| [[CX-0003]](#61-normative-references) | SAMM Aspect Meta Model | 1.1.0 | +| [[CX-0006]](#61-normative-references) | Registration and initial onboarding | 2.0.0 | +| [[CX-0010]](#61-normative-references) | Business Partner Number (BPN) | 2.0.0 | +| [[CX-0018]](#61-normative-references) | Dataspace Connectivity | 3.0.0 | +| [[CX-0126]](#61-normative-references) | Industry Core Part Type | 2.0.0 | + +*Table 2: List of mandatory standards* + +The usage of this standard may be complemented with the following Catena-X standards to further extend +the range of shortage prevention possibilities: + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0118]](#61-normative-references) | Delivery Information Exchange | 2.0.0 | +| [[CX-0120]](#61-normative-references) | Short-term Material Demand Exchange | 2.0.0 | +| [[CX-0122]](#61-normative-references) | Item Stock Exchange | 2.0.0 | +| [[CX-0145]](#61-normative-references) | Days of Supply Exchange | 1.0.0 | +| [[CX-0146]](#61-normative-references) | Supply Chain Disruption Notifications | 1.0.0 | + +*Table 3: List of non-mandatory complementary standards* + +#### 2.1.2 DATA REQUIRED + +No additional data requirements + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### CONVENTIONS FOR USE CASE POLICY IN CONTEXT DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization +of data within the Catena-X use cases has been outlined. A set of specific policies on data offering +and data usage level detail the conditions under which data may be accessed, shared, and used, +ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data +usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository [[CX-ODRL]](#62-non-normative-references). This document provides in-depth explanations of the + terms and conditions applied to data access and utilization, ensuring that all engagement with our data + is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. + Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +###### ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for +members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, +Data Provider maintains control over its anti-trust obligations when sharing certain data. In +particular, Data Provider may apply Access Policies to restrict access to a particular data offer +for only one Participant identified by a specific business partner number. + +- Membership +- BPNL + +###### ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use +the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are +provided via the ODRL policy repository [[CX-ODRL]](#62-non-normative-references). + +##### REMINDER OF ANTITRUST + +Notice and/or acknowledgement concepts to raise awareness of antitrust issues during use of this standard +are **RECOMMENDED**, for example through the implementation of a help desk or pop-up info. + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +This standard builds upon the Industry Core Part Type [[CX-0126]](#61-normative-references) and the Digital Twins in +Catena-X [[CX-0002]](#61-normative-references) standards. It follows the following design patterns: + +- Usage of the specific asset IDs and further identification data for the Digital Twin for the Part Type + (see [[CX-0126]](#61-normative-references)). +- Provisioning of the *PartTypeInformation* on supplier side (see [[CX-0126]](#61-normative-references)). + +Because only the supplier provides planned production output data for the Part Type Twin, the supplier is in charge of creating a twin that is identifiable for the customer. + +- The supplier of the part has a Digital Twin representation and is then able to offer + *Planned Production Output* data to customers. +- The customer, who orders or uses the part, has a Digital Twin representation to offer + *Planned Production Output* data to a supplier. +- To make the Part Type Twin identifiable for the customers, the supplier + - **MUST** create the Digital Twin first. + - **MUST** generate the Catena-X ID and ensure that the customer-specific asset IDs and submodel + descriptors are only accessible by the specific customer. + - **MAY** use the Digital Twin for multiple customers. + +The definition of identification data (Catena-X ID, Asset Administration Shell ID, specific asset ID) +**MUST** follow the Industry Core Part Type [[CX-0126]](#61-normative-references). Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for further details. + +> ***Note:*** The Part Type Twin's data is considered sensitive. Data providers **MUST** implement appropriate +measures ensuring that competitors-specific asset IDs and/or information about submodels is accessible +only to the data consumers it concerns, but not to their competitors. + +Figure 2 shows how the shared asset approach is realized. The orange lines show which submodels belong +to the respective AAS. All *Planned Production Output*-specific submodels are bound to the specific +Part Type's context e.g., meaning that the *Planned Production Output* aspect is described for the specific +catalog item on supplier and customer side represented by the AASs. The orange submodels are the +submodels used within this standard's context. The grey submodels are used within the Industry Core +[[CX-0126]](#61-normative-references)(*PartTypeInformation, SingleLevelBomAsPlanned, SingleLevelUsageAsPlanned*). +The blue dashed lines show the references between DTs based on Catena-X UUIDs and BPNL information that +may be resolved by the Item Relationship Service (see [[CX-0126]](#61-normative-references)). + +![Figure 2: Conceptual levels of provisioning digital twins](./assets/Figure_2.svg) +*Figure 2: Conceptual levels of provisioning digital twins* + +Figure 2 details two conceptual levels: + +- The Asset level contains the asset (Industry Core Part Type) represented by a Digital Twin. + The latter is provisioned as an Asset Administration Shell (AAS) within the decentralized Digital + Twin Registry (dDTR) of the data provider (supplier or customer). +- The Submodel level represents the actual information that are held by a Digital Twin (DT). Those + submodels follow the respective definition of the in Semantic Aspect Meta Model (SAMM) format + (see [Chapter 3](#3-aspect-model)). The dDTR only holds meta-information about the Submodel + (e.g. kind of submodel via semantic ID or connector endpoint information). + +## 3 ASPECT MODEL + +> *This section is normative* + +### 3.1 "PLANNED PRODUCTION OUTPUT" ASPECT MODEL + +#### 3.1.1 INTRODUCTION + +The *Planned Production Output* defines the set of quantities of a material that will be produced for +a customer until a given point in time. For the complete semantics and detailed description of its +properties refer to the SAMM model in [Chapter 3.1.5.1](#3151-rdf-turtle). + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the +"semantic-driven workflow" to create a submodel template specification [[SMT]](#62-non-normative-references). + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [[CX-0003]](#61-normative-references) as +input for the semantic-driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to [[CX-0003]](#61-normative-references). + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +> `urn:samm:io.catenax.planned_production_output:2.0.0` + +This identifier **MUST** be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The RDF turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional +file formats and serializations. It can be found under the following link: + +> [https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.planned_production_output/2.0.0/PlannedProductionOutput.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.planned_production_output/2.0.0/PlannedProductionOutput.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of +other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template +or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload +of the Asset Administration Shell for the API operation *"GetSubmodel"*. + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to [[SMT]](#62-non-normative-references). + +## 4 APPLICATION PROGRAMMING INTERFACE + +> *This section is normative* + +### 4.1 API USED TO EXCHANGE "PLANNED PRODUCTION OUTPUT" INFORMATION + +As described in [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids) this standard builds upon the [[CX-0002]](#61-normative-references) Digital Twins in Catena-X +and [[CX-0126]](#61-normative-references) Industry Core Part Type standards. Therefore, the APIs provided by the Digital Twin +standard are combined with the part identification defined in the Industry Core standard. This chapter +defines how the aforementioned standards and the [[CX-0018]](#61-normative-references) +standard **MUST** be used to facilitate the provisioning of *Planned Production Output* data. The +usage of the Discovery Services defined in [[CX-0001]](#61-normative-references), [[CX-0053]](#61-normative-references) is not mandatory, +because this standard assumes an already existing business relationship between the involved parties. + +The sequence diagram in *Figure 3* provides an overview of the interactions required to register the +Part Type Twin. + +- Steps 1 & 2: Register the dDTR access for the partner at the connector +- Steps 3 & 4: When using the repository pattern, create the submodel (and twin) +- Steps 5 & 6: Register the submodel endpoint for the partner at the connector +- Steps 7 & 8: Register or update the twin Shell Descriptor relying on the registered Connector asset + for the submodel endpoint and the identification data of the partners + +![Figure 3: Flow to create and register a digital twin](./assets/Figure_3.svg) +*Figure 3: Flow to create and register a digital twin* + +The sequence diagram in Figure 4 provides an overview of the interactions required when a supplier +(acting as data provider) provisions *Planned Production Output* data to a customer (acting as data consumer). + +The flow "*Customer reads (updated) Submodel from Supplier*" visualizes the sequence of calls when consuming data: + +- Steps 3 - 8: Contract dDTR usage in the connector. +- Steps 9 - 12: Lookup the Industry Core Part Type Twin for a Part Type based on the common identification data. +- Steps 13 - 18: Read the Shell Descriptor of the Industry Core Part Type Twin to extract the *Planned Production Output* + submodel endpoint (registered at the connector). +- Steps 19 - 24: Contract the *Planned Production Output* data usage in the connector. +- Steps 25 - 29: Consume and use the *Planned Production Output* data. + +![Figure 4: Flow to lookup a digital twin and get a submodel.](./assets/Figure_4.svg) +*Figure 4: Flow to lookup a digital twin and get a submodel.* + +> ***Note:*** Depending on the use of repository patterns and the design of the Digital Twins, the data +may be updated manually in the Submodel endpoint. + +#### 4.1.1 CONNECTOR DATA ASSET STRUCTURE + +The endpoints for the dDTR and the Submodel Endpoint **MUST** be made available BUT they **MUST NOT** +be directly called data consumer. Rather, for access to dDTRs and Submodels, there **MUST** be contracts +negotiated in accordance with the DSP. Therefore, the endpoints **MUST** be offered as connector data +assets. To make these assets easily identifiable in the connector's catalog, each asset **MUST** be +configured with a set of properties as described in the corresponding sections below. + +The following table provides an overview of the connector data assets that the parties **MUST** offer +to be able to provision and/or consume *Planned Production Output* data. + +| **Party** | **REQUIRED** | **Asset** | **Purpose** | +| --- | --- | --- | --- | +| Supplier | Yes | "Digital Twin Registry" | Allows a consumer to query for Part Type Twins and their *Planned Production Output* submodels. | +| Supplier | Yes | "Submodel Planned Production Output" | Allows a consumer to read actual *Planned Production Output* data related to a Part Type Twin. | + +*Table 4: Connector data assets* + +In the section below the asset definitions of two different kinds of assets are defined. + +##### Connector Data Asset Structure for "Digital Twin Registry" + +To allow partners to find the "Planned Production Output" data for a specific Industry Core Part Type Twin, +the provider **MUST** register a connector data asset (see details in [[CX-0018]](#61-normative-references)) specifying the address +of the Digital Twin Registry of the provider (see [[CX-0002]](#61-normative-references)). + +The data asset **MUST** be configured with the set of properties as defined in the table below. + +| **Object** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***@id*** | Identifier of the asset | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. | +| properties | [**http://purl.org/dc/terms/type**](http://purl.org/dc/terms/type) | Defines the "Digital Twin Registry" according to the Catena-X taxonomy. | **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#DigitalTwinRegistry"}` to allow filtering the data assets catalog for the respective "Digital Twin Registry". | +| properties | [**https://w3id.org/catenax/ontology/common#version**](https://w3id.org/catenax/ontology/common#version) | The version of the standard defining the implemented API of the "Digital Twin Registry" | **MUST** correspond to the version of the standard defining the Interfaces of the "Digital Twin Registry". The value **MUST** be set to `"3.0"` for "Digital Twin Registries" used by this standard. | +| dataAddress | **@type** | Type of the DataAddress node. | **MUST** be set to `"DataAddress"`. | +| dataAddress | ***baseUrl*** | Defines the HTTPS endpoint of the corresponding "Digital Twin Registry Endpoint". | The `{{ DIGITAL_TWIN_REGISTRY_ENDPOINT }}` refers to an URL under which the API of the "Digital Twin Registry" endpoint is available. HTTPS transport protocol **MUST** be used. | +| dataAddress | ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body | **SHOULD** be set to `"false"` to not allow the API endpoint to receive a HTTPS body via the HTTPS request. | +| dataAddress | ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method | **SHOULD** be set to `"false"` to only allow the API endpoint to receive GET requests. | +| dataAddress | ***proxyPath*** | Defines whether the endpoint allows to proxy paths for the URL | **MUST** be set to `"true"` to allow the API endpoint to receive appended paths of the HTTPS request. | +| dataAddress | ***type*** | Defines the type of data plane extension handling the data exchange | **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. | + +*Table 5: Connector data assets request properties* + +Additionally security identification information **MAY** be added to secure the "Decentralized Digital Twin Registry". + +When searching the Catalog of a provider, a consumer **SHOULD** use the following properties AND +their values to identify the Data Asset specifying "Digital Twin Registry". In the connector Data Asset +descriptions the API version valid for this standard is mentioned for the property +[`https://w3id.org/catenax/ontology/common#version`](https://w3id.org/catenax/ontology/common#version). The requester of a Data Asset **MUST** be +able to handle multiple Data Asset for this endpoint, being differentiated only by the version. +The requester **SHOULD** choose the Data Asset set with the highest compatible version number implemented +by themselves. If the requester cannot find a compatible version with their own, the requester **MUST** +terminate the data transfer. + +| **Property** | **Value** | +| --- | --- | +| http://purl.org/dc/terms/type | `{"@id": "https://w3id.org/catenax/taxonomy#DigitalTwinRegistry"}` | + +*Table 6: Connector data assets request properties values.* + +An example connector data asset definition is given below. + +>**Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "http://purl.org/dc/terms/" + }, + "@id": "{{CONNECTOR_ASSET_ID}}", + "properties": { + "dct:type": {"@id": "cx-taxo:DigitalTwinRegistry"}, + "cx-common:version": "3.0" + }, + "privateProperties": { + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ DIGITAL_TWIN_REGISTRY_ENDPOINT }}", + "proxyQueryParams": "true", + "proxyBody": "false", + "proxyPath": "true", + "proxyMethod": "false", + } +} +``` + +##### Connector Data Asset Structure for "Submodel" + +To allow partners to receive the "Planned Production Output" data as defined in [Chapter 3](#3-aspect-model), +the provider **MUST** register a connector data asset (see details in[[ CX-0018]](#61-normative-references)) specifying the +address of the submodel endpoint (see [[CX-0002]](#61-normative-references)) providing the actual data. + +The data asset **MUST** be configured with the set of properties as defined in the table below. + +| **Object** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***@id*** | Identifier of the asset | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. | +| properties | [**http://purl.org/dc/terms/type**](https://purl.org/dc/terms/type) | Defines the "Submodel API" according to the Catena-X taxonomy. | **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#Submodel"}` to allow filtering the data assets catalog for the respective "Submodel API". | +| properties | [**https://admin-shell.io/aas/3/0/HasSemantics/semanticId**](https://admin-shell.io/aas/3/0/HasSemantics/semanticId) | The semantic identifier of the "Planned Production Output" SAMM. | **MUST** be set to `{"@id": "urn:samm:io.catenax.planned_production_output:2.0.0#PlannedProductionOutput"}` to externally define how the Submodel must be interpreted. **MUST NOT** be set, if different submodels may be returned by this API. | +| properties | [**https://w3id.org/catenax/ontology/common#version**](https://w3id.org/catenax/ontology/common#version) | Version of the Submodel Interface Specification | **MUST** be set to `"3.0"` in accordance to [[CX-0002]](#61-normative-references). | +| dataAddress | **@type** | Type of the DataAddress node. | **MUST** be set to `"DataAddress"`. | +| dataAddress | ***baseUrl*** | Defines the HTTPS Submodel endpoint provisioning the *Planned Production Output* data | The `{{ SUBMODEL_ENDPOINT }}` refers to an URL under which the Submodel API Endpoint ([[CX-0002]](#61-normative-references)) is available to provide the "Planned Production Output" . HTTPS transport protocol **MUST** be used. | +| dataAddress | ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body | **SHOULD** be set to `"false"` to not allow the API endpoint to receive a HTTPS body via the HTTPS request. | +| dataAddress | ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method | **SHOULD** be set to `"false"` to only allow the API endpoint to receive GET requests. | +| dataAddress | ***proxyPath*** | Defines whether the endpoint allows to proxy paths for the URL | **MUST** be set to `"true"` to allow the API endpoint to receive appended paths of the HTTPS request. Setting this parameter depends on the implementation of the submodel lookup. | +| dataAddress | ***type*** | Defines the type of data plane extension handling the data exchange | **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. | + +*Table 7: Connector data assets request properties* + +Additionally security identification information **MAY** be added to secure the "Submodel API". + +When searching the data assets catalog of a provider, a consumer **SHOULD** use the `assetId` previously +determined via `subprotocolBody` of the SubmodelDescriptor's endpoint definition of subprotocol type "DSP". +Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for the definition of the `subprotocolBody`. + +| **Property** | **Value** | +| --- | --- | +| [https://w3id.org/edc/v0.0.1/ns/id](https://w3id.org/edc/v0.0.1/ns/id) | `{{CONNECTOR_ASSET_ID}}` specified in the DSP endpoint of the SubmodelDescriptor (see [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition)) | + +*Table 8: Connector data assets request properties values* + +An example connector data asset definition is given below. + +>**Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "http://purl.org/dc/terms/", + "aas-semantics": "https://admin-shell.io/aas/3/0/HasSemantics/" + }, + "@id": "{{CONNECTOR_ASSET_ID}}", + "properties": { + "dct:type": {"@id": "cx-taxo:Submodel"}, + "cx-common:version": "3.0", + "aas-semantics:semanticId": {"@id": "urn:samm:io.catenax.planned_production_output:2.0.0#PlannedProductionOutput"} }, + "privateProperties": { + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ SUBMODEL_ENDPOINT }}", + "proxyQueryParams": "false", + "proxyBody": "false", + "proxyPath": "true", + "proxyMethod": "false", + } +} +``` + +#### 4.1.2 INDUSTRY CORE PART TYPE TWIN REGISTRATION AND DEFINITION + +##### 4.1.2.1 SHELL DESCRIPTOR REGISTRATION + +To allow partners to receive the actual "*Planned Production Output*" data as defined in [Chapter 3](#3-aspect-model), +the provider **MUST** register a Shell Descriptor in the dDTR (see [[CX-0002]](#61-normative-references)) so that a partner: + +- May lookup the Industry Core Part Type Twin based on known identification data. +- May identify the connector endpoint providing access to the *Planned Production Output* submodel data. + +The Shell Descriptors represent each an Industry Core Part Type Twin and **MUST** follow the rules as defined +in [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids). + +The Shell Descriptor **MUST** be configured with the set of properties as defined in the table below. + +| **Object in ShellDescriptor** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***id*** | Defines the technical ID of the Asset Administration Shell representing a partner's twin. | **MUST** be unique following Industry Core Part Type standard ([[CX-0126]](#61-normative-references)) and is a technical Id randomly assigned as multiple Part Type Twins may be created for one Part Type. E.g. this number differs for the twins created at supplier and customer side. | +| | ***globalAssetId*** | Defines the Catena-X ID of the twin. | **MUST** be aligned with the partner's material. When referring to the same Part Type Twin, the same number **MUST** be used (see [[CX-0126]](#61-normative-references)). | +| | **specificAssetIds** | Identifiers that may be used to lookup Part Type Twins. | **MUST** be set to according to the Industry Core Part Type standard ([[CX-0126]](#61-normative-references)). See *Table 10* for respective specific asset IDs. The `"customerPartId"` **MUST** be set by Customers and **SHOULD** be set by Suppliers. | +| submodelDescriptor | **id** | Technical identifier of a SubmodelDescriptor. | **MUST** be set to a unique identifier. | +| submodelDescriptor | **semanticId** | The semantic identifier of the "Planned Production Output" SAMM. | **MUST** be set to `{ "type": "ExternalReference", "keys": [{ "type": "GlobalReference", "value": "urn:samm:io.catenax.planned_production_output:2.0.0#PlannedProductionOutput" }] }` to externally define how the Submodel must be interpreted. | +| submodelDescriptor > endpoint | **interface** | Defines the Submodel Interface [[CX-0002]](#61-normative-references) and the version. | **MUST** be set to `"SUBMODEL-3.0"` to rely on current specification. | +| submodelDescriptor > endpoint > protocolInformation | **href** | Defines the direct link to the public API of the connector's data plane with a path that **SHOULD** be appended by the proxy, if needed. | **MUST** be set to the public API of the dataplane providing the data with the path appended to directly access the submodel. | +| submodelDescriptor > endpoint > protocolInformation | **subprotocol** | Defines the usage of the connector based on DSP to access and use the submodel. | **MUST** be set to `"DSP"` to define the connector endpoint of the subprotocol. | +| submodelDescriptor > endpoint > protocolInformation | **subprotocolBody** | Defines the asset id in the connector and the connector address to access and use the submodel. | **MUST** be set to `"id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}"` to provide the necessary information for contracting the submodel endpoint. Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for the definition of the asset of the subprotocolBody. | + +*Table 9: Properties relevant for the Shell Descriptor definition* + +When searching the submodel in the dDTR of a provider, a consumer **SHOULD** use the specific asset IDs +as defined in [[CX-0126]](#61-normative-references). Table 10 gives an overview of the specific asset IDs that the data provider +added to the ShellDescriptor so that the data consumer may find the Industry Core Part Type Twin. + +| **Specific Asset Id** | **Value** | +| --- | --- | +| digitalTwinType | "PartType". Set to identify twins compliant to the Industry Core Part Type (see [[CX-0126]](#61-normative-references)). | +| manufacturerId | Supplier / Manufacturer partner BPNL (see [[CX-0010]](#61-normative-references)) | +| manufacturerPartId | Supplier / Manufacturer partner identification number of the part. | +| customerPartId | Customer partner identification number of the part. | + +*Table 10: Specific asset IDs of Industry Core Part Type Twins proposed to be used to lookup a twin in the dDTR* + +The Shell Descriptor defines the metadata of the Industry Core Part Type Twin. The following example +Shell Descriptor represents a supplier's Shell Descriptor of a supplier who provides two customers access +to a "Planned Production Output" submodel. For further information on the creation of Part Type Twins, +refer to [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids). + +Following [[CX-0002]](#61-normative-references), when searching the data assets catalog of a provider, a consumer **SHOULD** +use the `assetId` determined via `subprotocolBody` of the SubmodelDescriptor's endpoint definition +of subprotocol type `"DSP"` of the Submodel Descriptor of interest. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "id": "{{TECHNICAL_TWIN_ID}}", + "globalAssetId": "{{MATERIAL_NUMBER_CX}}", + "idShort": "Semiconductor", + "specificAssetIds": [ + { + "name": "digitalTwinType", + "value": "PartType", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "manufacturerPartId", + "value": "{{MATERIAL_NUMBER_SUPPLIER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "manufacturerId", + "value": "{{SUPPLIER_BPNL}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "customerPartId", + "value": "{{MATERIAL_NUMBER_CUSTOMER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "customerPartId", + "value": "{{MATERIAL_NUMBER_OTHER_CUSTOMER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + } + ], + "submodelDescriptors": [ + { + "id": "e5c96ab5-896a-482c-8761-efd74777ca97", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.item_stock:2.0.0#PlannedProductionOutput" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "{{SUPPLIER_CONNECTOR_DATAPLANE_PUBLIC_API}}/{{PATH_IF_NEEDED}}", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ] + }, + { + "id": "a6c96ab5-896a-482c-8761-efd74777ca99", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.item_stock:2.0.0#PlannedProductionOutput" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "{{SUPPLIER_CONNECTOR_DATAPLANE_PUBLIC_API}}/{{PATH_IF_NEEDED}}", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ] + } + ] +} +``` + +##### 4.1.2.2 LOOKING UP A PART TYPE TWIN IN THE DDTR + +To query the dDTR of a data provider, after contracting the usage via the data provider's connector +(see [[CX-0018]](#61-normative-references)), the lookup API (see [[CX-0002]](#61-normative-references)) can be used relying on the specific +asset IDs defined by the Industry Core Part Type (see [[CX-0126]](#61-normative-references)) that can be seen in +Table 10 (table of shellDescriptorRegistration with specific asset IDs). + +An example call relying on all information is given in the code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{PARTNER_CONNECTOR_DATA_PLANE}}/lookup/shells?assetIds={"name":"digitalTwinType", "value": "PartType"},{"name":"manufacturerPartId", "value": "{{MATERIAL_NUMBER_SUPPLIER}}"},{"name":"manufacturerId", "value": "{{SUPPLIER_BPNL}}"},{"name":"customerPartId", "value": "{{MATERIAL_NUMBER_CUSTOMER}}"} +``` + +As a result identifiers of the ShellDescriptors will be returned. With this data, a data provider can +read the ShellDescriptor to extract the endpoint data of the data provider. An example is given in the +code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{PARTNER_CONNECTOR_DATA_PLANE}}/shell-descriptors/{{AAS_IDENTIFIER}} +``` + +##### 4.1.2.3 FETCHING SUBMODEL DATA + +To fetch the *Planned Production Output* Submodel data at the submodel endpoint of a data provider, after +contracting the usage via the data provider's connector (see [[CX-0018]](#61-normative-references)), the submodel API (see [[CX-0002]](#61-normative-references)) +can be used. + +An example call relying on all information is given in the code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{HREF_PATH}}/$value +``` + +## 5 PROCESSES + +> *This section is normative* + +The processes described are intended to serve as guidance and recommendation for the use of the +"*Planned Production Output Exchange*" standard in different scenarios. In the field a combination +of several scenarios is common practice. This process description does not claim to be exhaustive, +but rather is intended to support the involved parties in finding beneficial and legally acceptable +solutions. + +### 5.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Customer** | The customer acts as the data consumer in this standard. | A business partner that procures items from suppliers and requests information about their planned production output. | +| **Supplier** | The supplier acts as the data provider in this standard. | A business partner that supplies items to customers. As such, a supplier is responsible for providing consistent and up-to-date Planned Production Output data. | + +*Table 11: Actors and roles* + +### 5.2 PROCESS REPRESENTATIONS + +**5.2.1 SINGLE CUSTOMER SCENARIO** + +The most straightforward process is described as a relationship between one supplier and one +customer where an item is specifically planned and produced for the customer. There are no third +party customers that procure the same material from the supplier. + +The production output is planned by the supplier on a daily basis so that this data should be +provided without further adaptions to the customer. Also having multiple customers may be handled as +a single customer scenario, if customer-specific material numbers are used for the production +planning in the internal systems of the supplier. An example where the total *Planned Production Output* +is allocated to a single customer is shown in the table below: + +| | **Day 1** | **Day 2** | **Day 3** | **Sum** | +| --- | --- | --- | --- | --- | +| **Total Planned Production Output** | 15 | 15 | 20 | 50 | +| **Allocated to Customer A** | 15 | 15 | 20 | 50 | + +*Table 12: Planned Production Output for a single customer scenario* + +#### 5.2.2 MULTIPLE CUSTOMER SCENARIO + +To have multiple customers for a specific item as a supplier is a scenario that requires a proper +adjustment of the *Planned Production Output* data provided by the supplier. The supplier must +not simply provide the total quantities of the *Planned Production Output* to both customers since +they are not specific. On the one hand, they are not helpful and, on the other hand, they cause a +legal issue if they allow customers to draw conclusions about each other. A simplified illustration +of the situation where the total *Planned Production Output* is allocated to different customers is +shown in the table below: + +| | **Day 1** | **Day 2** | **Day 3** | **Sum** | +| --- | --- | --- | --- | --- | +| **Total Planned Production Output** | 35 | 15 | 85 | 135 | +| **Allocated to Customer A** | 15 | 15 | 20 | 50 | +| **Allocated to Customer B** | 20 | 0 | 65 | 85 | + +*Table 13: Planned Production Output for a multiple customer scenario* + +Since sharing data on a horizontal level is critical from a legal perspective a supplier must +make sure that the data he provides to a customer does not include information that allows +conclusions about a competitor. This standard does not and cannot check data for being legally +compliant on a semantic and technical level. Therefore, each user must make sure to comply with +applicable laws when providing information. For the allocation of *Planned Production Output* data +to a specific partner, it is recommended to evaluate the following proposals: + +**Derive from orders or call-offs that have been received:** + +1. get orders or call-offs +2. calculate quotations based on needed amounts per day / week +3. apply quotation per day or production order + +**Derive from incoming Short-Term Material Demand** **[[CX-0120]](#61-normative-references):** + +1. request latest demand per customer per site +2. determine the needed end of production date per customer and site +3. calculate quotations based on the needed amount per day / week +4. apply quotations per day or production order + +Potential drawbacks: heavyweight computation with external involvement + +**Derive from scheduled deliveries** **[[CX-0118]](#61-normative-references):** + +1. get the estimated time of departure (ETD) for the scheduled deliveries per customer and site +2. calculate quotations based on needed amounts per day +3. apply quotation per day or production order + +Potential drawbacks: scheduled deliveries might be derived from produced goods (wrong circularity) + +#### 5.2.3 NON-DAILY BASED PLANNED PRODUCTION OUTPUT + +One possible scenario is that production planning is not done on a daily basis. The planned +production output is determined by a production order whose estimated date of completion does not +necessarily match with the real completion date of the produced items. The example below shows a +scenario where the complete production order of a supplier equals to a total of 45 items planned to +be finished on the third day. However, in reality, the production will already start on the first +day and will only be finished on day three. + +- in total 45 items are planned as production output for the third day +- the actual production starts on day one with an output of 15 items per day +- the total planned quantity will be finished on day three + +| | **Day 1** | **Day 2** | **Day 3** | **Sum** | +| --- | --- | --- | --- | --- | +| **Planned Production Output** | 0 | 0 | 45 | 45 | +| **Actual Production Output** | 15 | 15 | 15 | 45 | + +*Table 14: Non-daily-based Planned Production Output scenario* + +In this case, the accuracy of the planned production output data provided to the customer is +reduced. This loss of granularity and the weakening of the information base can be particularly +disadvantageous in the event of a shortage. Hence it is recommended to plan the production +output on a daily basis. + +However, if this is not possible the data providing supplier **SHOULD** consider working with +partial completion confirmations for the already finished items that belong to a *Planned Production Output*. +Confirming partially completed production orders lowers on the one hand the remaining planned production +quantity and on the other hand increases the available and allocated *Item Stock* (see [[CX-0122]](#62-non-normative-references)). +This enables the data-consuming customer to be provided with a more accurate and up-to-date representation +of the still remaining *Planned Production Output* quantities as well as with available stock data. +In any case, the supplier must ensure that the information is consistent and plausible. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [CX-0001] | EDC Discovery API | 1.0.2 | +| [CX-0002] | Digital Twins in Catena-X | 2.2.0 | +| [CX-0003] | SAMM Aspect Meta Model | 1.1.0 | +| [CX-0006] | Registration and initial onboarding | 2.0.0 | +| [CX-0010] | Business Partner Number (BPN) | 2.0.0 | +| [CX-0018] | Dataspace Connectivity | 3.0.0 | +| [CX-0053] | Discovery Finder and BPN Discovery Service APIs | 1.1.0 | +| [CX-0118] | Delivery Information Exchange | 2.0.0 | +| [CX-0120] | Short-term Material Demand Exchange | 2.0.0 | +| [CX-0122] | Item Stock Exchange | 2.0.0 | +| [CX-0126] | Industry Core Part Type | 2.0.0 | +| [CX-0128] | Demand and Capacity Management | 2.0.0 | +| [CX-0145] | Days of Supply Exchange | 1.0.0 | +| [CX-0146] | Supply Chain Disruption Notifications | 1.0.0 | + +### 6.2 NON-NORMATIVE REFERENCE + +> *This section is non-normative* + +| **Context** | **Link** | +| --- | --- | +| [CX-OMW] | Catena-X Operating Model Whitepaper. Download from: [https://catena-x.net/fileadmin/\_online\_media\_/CX\_Operating\_Modelv2.1_final.pdf](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf) | +| [CX-ODRL] | Catena-X ODRL Profile repository: https://github.com/catenax-eV/cx-odrl-profile | +| [RFC2119] | Bradner, S. Key words for use in RFCs to Indicate Requirement Levels. Available online: https://datatracker.ietf.org/doc/html/rfc2119 | +| [RFC8174] | Leiba, B. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. Available online: https://datatracker.ietf.org/doc/html/rfc8174 | +| [SMT] | How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf | +| [IDTA-01002-3-0] | Specification of the Asset Administration Shell Part 2: Application Programming Interfaces. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API.pdf | + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_1.svg b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_1.svg new file mode 100644 index 000000000..0147b5de4 --- /dev/null +++ b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_1.svg @@ -0,0 +1,4 @@ + + + +
    Data Provider
    Data Provider
    Connector
    Connector
    Busines Application
    Busines App...
    Catena-X Core Service Provider
    Catena-X Core Service Provider
    IAM
    IAM
    Credential Service
    Credential S...
    Keycloak
    Keycloak
    Data Consumer
    Data Consumer
    Connector
    Connector
    Busines Application
    Busines Applicati...
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
    (8) Get Submodel
    (8) Get Su...
    (5) Query dDTR for Twin and submodel
    (5) Query dDTR for Twin and submodel
    (4) Connector Communication
      (Catalog / Contracting / Transfer)  
    (4) Connector Communication...
    dDTR
    dDTR
    Submodel Endpoint
    Submodel E...
    (10) Get Submodel
    (10) Get S...
    (3) Register Twin
    with Submodels
    (3) Register Twin...
    (2) Register Submodel Endpoint
     at Connector
    (2) Register Submodel Endpoint...
    (9)
    (9)
    Text
    Text
    (6) Get lookup/shells
    by specific asset ids
    (6) Get lookup/shells...
    (1) Register dDTR at Connector
    (1) Register dDTR at Connector
    (7) Get shell-descriptors
    by AAS ID
    (7) Get shell-descriptors...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_2.svg b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_2.svg new file mode 100644 index 000000000..dad1f86a5 --- /dev/null +++ b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_2.svg @@ -0,0 +1,4 @@ + + + +
    PartType for Material (e.g. "Semiconductor")
    PartType for Material...
    Supplier
    Supplier
    Customer
    Custom...
    Asset
    registered in dDTR as AAS
    Asset...
    Submodel
    Submodel
    PartType for Material "Control Unit"
    PartType for Materia...
    Planned Production Output
    Planned Production O...
    PartTypeInformation
    PartTypeInformation
    SingleLevelUsageAs Planned
    SingleLevelUsageAs P...
    submodel of
    submodel of
    submodel of
    submodel of
    references twin
    references twin
    PartTypeInformation
    PartTypeInformation
    SingleLevel
    BomAsPlanned
    SingleLevel...
    references twin
    references twin
    submodel of
    submodel of
    submodel of
    submodel of
     Legend
     Legend
    Digital Twin in DTR
    Digital Twin in DTR
    Submodel (CX-0121)
    Submodel (CX-0121)
    Submodel (IC Part Type)
    Submodel (IC Part Type)
    submodel of
    submodel of
    references twin
    references twin
    submodel of
    submodel of    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_3.puml b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_3.puml new file mode 100644 index 000000000..f4aa4b013 --- /dev/null +++ b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_3.puml @@ -0,0 +1,37 @@ +@startuml Figure_3 +title Registration of IC Part Type Twin + +autonumber + +box "Supplier" #LightBlue + participant SupplierApplication as "Application" + participant SupplierDTR as "dDTR" + participant SupplierSubmodelEndpoint as "Submodel Endpoint" + participant SupplierEDC as "Connector" +end box + +box "Customer" #LightGreen + participant CustomerEDC as "Connector" + participant CustomerSubmodelEndpoint as "Submodel Endpoint" + participant CustomerDTR as "dDTR" + participant CustomerApplication as "Application" +end box + +== Supplier registers IC Part Type Twin with Submodel for Customer == + SupplierApplication -> SupplierEDC: Register dDTR for partner at Connector + activate SupplierEDC + return OK + + note over SupplierSubmodelEndpoint, SupplierApplication: Keeping Submodel updated only needed\nfor repository pattern + SupplierApplication -> SupplierSubmodelEndpoint: Create Submodel + activate SupplierSubmodelEndpoint + return OK + + SupplierApplication -> SupplierEDC: Register endpoint of Submodel for READ access for partner at Connector + activate SupplierEDC + return OK + + SupplierApplication -> SupplierDTR: Register IC Part Type Twin Shell Descriptor\n with Submodel endpoint\nfor Partner in dDTR\n(DSP endpoint) + activate SupplierDTR + return OK +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_3.svg b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_3.svg new file mode 100644 index 000000000..f2d90c48e --- /dev/null +++ b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_3.svg @@ -0,0 +1,47 @@ +Registration of IC Part Type TwinSupplierCustomerApplicationApplicationdDTRdDTRSubmodel EndpointSubmodel EndpointConnectorConnectorConnectorConnectorSubmodel EndpointSubmodel EndpointdDTRdDTRApplicationApplicationSupplier registers IC Part Type Twin with Submodel for Customer1Register dDTR for partner at Connector2OKKeeping Submodel updated only neededfor repository pattern3Create Submodel4OK5Register endpoint of Submodel for READ access for partner at Connector6OK7Register IC Part Type Twin Shell Descriptorwith Submodel endpointfor Partner in dDTR(DSP endpoint)8OK \ No newline at end of file diff --git a/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_4.puml b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_4.puml new file mode 100644 index 000000000..b2803a457 --- /dev/null +++ b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_4.puml @@ -0,0 +1,86 @@ +@startuml Figure_4 + +title Lookup of IC Part Type Twin + +autonumber + +box "Supplier" #LightBlue + participant SupplierApplication as "Application" + participant SupplierDTR as "dDTR" + participant SupplierSubmodelEndpoint as "Submodel Endpoint" + participant SupplierEDC as "Connector" +end box + +box "Customer" #LightGreen + participant CustomerEDC as "Connector" + participant CustomerSubmodelEndpoint as "Submodel Endpoint" + participant CustomerDTR as "dDTR" + participant CustomerApplication as "Application" +end box + + +== Supplier updates Submodel information (repository pattern only) == + + note over SupplierEDC, SupplierApplication: Keeping Submodel updated only needed\nfor repository pattern + SupplierApplication -> SupplierSubmodelEndpoint: Update Submodel\ninformation + activate SupplierSubmodelEndpoint + return OK + + +== Customer reads (updated) Submodel from Supplier == + + CustomerApplication -> CustomerEDC: Query Connector Catalog for Supplier dDTR access + activate CustomerEDC + + CustomerEDC <-> SupplierEDC: DSP communication + + return Catalog + + CustomerApplication -> CustomerEDC: Negotiate Contract and init transfer + activate CustomerEDC + CustomerEDC <-> SupplierEDC: DSP communication + return OK + + CustomerApplication -> SupplierEDC: Query DTR for IC Part Type Twin based on specific asset ids + activate SupplierEDC + SupplierEDC -> SupplierDTR: forward request based on\nConnector asset definitions\n(consumer proxy) + activate SupplierDTR + SupplierDTR --> SupplierEDC + deactivate SupplierDTR + return ShellDescriptor Ids + + CustomerApplication <- CustomerApplication: select ShellDescriptor ID\nto get ShellDescriptor for\nIC Part Type Twin + + CustomerApplication -> SupplierEDC: Lookup IC Part Type Twin based on ShellDescriptor Id + activate SupplierEDC + SupplierEDC -> SupplierDTR: forward request based on\nConnector asset definitions\n(consumer proxy) + activate SupplierDTR + SupplierDTR --> SupplierEDC + deactivate SupplierDTR + return ShellDescriptor + + CustomerApplication <- CustomerApplication: Extract DSP Endpoint\nand Connector Asset ID\nfor Submodel + + CustomerApplication -> CustomerEDC: Query Connector Catalog for Submodel based on\nConnector Asset ID + activate CustomerEDC + + CustomerEDC <-> SupplierEDC: DSP communication + + return Catalog + + CustomerApplication -> CustomerEDC: Negotiate Contract for Submodel and init transfer + activate CustomerEDC + CustomerEDC <-> SupplierEDC: DSP communication + return OK + + CustomerApplication -> SupplierEDC: Read Submodel + activate SupplierEDC + SupplierEDC -> SupplierSubmodelEndpoint: forward request based on\nConnector asset definitions\n(consumer proxy) + activate SupplierSubmodelEndpoint + SupplierSubmodelEndpoint --> SupplierEDC + deactivate SupplierSubmodelEndpoint + return Submodel + + CustomerApplication <- CustomerApplication: Use Submodel + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_4.svg b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_4.svg new file mode 100644 index 000000000..a868a26e1 --- /dev/null +++ b/docs/standards/CX-0121-PlannedProductionOutputExchange/assets/Figure_4.svg @@ -0,0 +1,96 @@ +Lookup of IC Part Type TwinSupplierCustomerApplicationApplicationdDTRdDTRSubmodel EndpointSubmodel EndpointConnectorConnectorConnectorConnectorSubmodel EndpointSubmodel EndpointdDTRdDTRApplicationApplicationSupplier updates Submodel information (repository pattern only)Keeping Submodel updated only neededfor repository pattern1Update Submodelinformation2OKCustomer reads (updated) Submodel from Supplier3Query Connector Catalog for Supplier dDTR access4DSP communication5Catalog6Negotiate Contract and init transfer7DSP communication8OK9Query DTR for IC Part Type Twin based on specific asset ids10forward request based onConnector asset definitions(consumer proxy)11 12ShellDescriptor Ids13select ShellDescriptor IDto get ShellDescriptor forIC Part Type Twin14Lookup IC Part Type Twin based on ShellDescriptor Id15forward request based onConnector asset definitions(consumer proxy)16 17ShellDescriptor18Extract DSP Endpointand Connector Asset IDfor Submodel19Query Connector Catalog for Submodel based onConnector Asset ID20DSP communication21Catalog22Negotiate Contract for Submodel and init transfer23DSP communication24OK25Read Submodel26forward request based onConnector asset definitions(consumer proxy)27 28Submodel29Use Submodel \ No newline at end of file diff --git a/docs/standards/CX-0122-ItemStockExchange/CX-0122-ItemStockExchange.md b/docs/standards/CX-0122-ItemStockExchange/CX-0122-ItemStockExchange.md new file mode 100644 index 000000000..3ecdbfaf0 --- /dev/null +++ b/docs/standards/CX-0122-ItemStockExchange/CX-0122-ItemStockExchange.md @@ -0,0 +1,1124 @@ +# CX-0122 Item Stock Exchange 2.0.0 + +## ABSTRACT + +The raising and management of *Item Stock* data is the task of ERP systems. Accurate inventory +management is a decisive factor for stable delivery capability for suppliers and an important +component of secure production capability for customers. Continuous monitoring of the *Item Stock* +between suppliers and customers ensures important information for the company's own production +planning and management. This information exchange is key to early detect and evaluate supply +shortage issues. Moreover, standardized interfaces between ERP systems often exist only for order +planning and execution. However, the necessary exchanging this information manually e.g. by phone or +e-mail is error-prone and slow. To mitigate inefficient and faulty communication, this document +defines a standardized approach for exchanging *Item Stock data* in an interoperable manner. A +common description of the *Item Stock* based on a standardized semantic definition is fundamental +for facilitating such an exchange. + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +Changes: + +- integration and usage of digital twins as defined in [[CX-0002]](#61-normative-references) Digital Twins in Catena-X +- harmonization of aspect model in accordance with [[CX-0126]](#61-normative-references) Industry Core: Part Type +- discontinuation of the proprietary API used in v1.0.0 of this standard +- grammatical, spelling and semantic improvements + +New Content: + +- added a note on the obligation of standard implementers to make aware that sensitive data is being + handled, see [[Chapter 2.1.3]](#213-additional-requirements) + +## 1 INTRODUCTION + +This document defines the standardized exchange of *Item Stock* data within the Catena-X network. +The *Item Stock* semantically is the actual quantity of reserved (here called allocated) material +for a partner that has not yet been shipped from the supplier's site or has already arrived at the +customer's site and has not yet been used for production. The semantic model is presented in the +Aspect Model Notation with all individual fields, formats and associated JSON schema. The +standardization of the *ItemStock* semantic model and an exchange API enables participants in the +value chain to share information about material and product stock in a timely manner, thus ensuring +that the possible solution space for mitigating a supply shortage is maximized. + +The *Item Stock* is related to a business relationship between the partners (an order / call-off +exists). Legal framework conditions and business aspects play an important role, for example in the +context of multi-sourcing, where no horizontal exchange of information may take place. The aim of this +standard is to ensure a secure exchange of stock data for active monitoring and the associated +prevention of bottlenecks and shortages. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following roles defined in [[CX-OMW]](#62-non-normative-reference): + +- **Data Providers** willing to provide *Item Stock* data +- **Data Consumers** interested in requesting and receiving *Item Stock* data +- **Business Application Providers** interested in providing solutions implementing this standard +- **Consulting Services Providers** interested in supporting companies fulfilling the standard + +The scope of this standard is only the Item Stock aspect model and API. It describes +the exchange of Item Stock data through a connector in accordance to [[CX-0018]](#61-normative-references). + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +A typical order-based procurement process includes a customer that places an order and a supplier +fulfilling it. Material may be either on stock at the supplier's site when it has been produced and +is ready to be shipped to the customer, or at the customer's site when it has been delivered and has +not yet been used for production. Those kinds of inventories are referred to as *Item Stock*. +Information about *Item Stock* quantities it is key to early detect and evaluate short-term supply +shortages on the customer or supplier side. Also it can help reduce the total amount of stored +material within the supply chain when partners share information on their materials inventory. + +*Figure 1* shows the high-level architecture of the *Item Stock* exchange in the Catena-X dataspace +and the services that are involved. Both the data provider and the data consumer must be members of +the Catena X network in order to communicate with each other. With the help of the Credential Service +and the Identity Access Management (IAM) each participant can authenticate itself, verify the identity +of the requesting party and decide whether to authorize the request. The *Item Stock* data is +provisioned in accordance with [[CX-0002]](#61-normative-references). + +![Figure 1: High-level architecture of the Item Stock exchange in Catena-X](./assets/Figure_1.svg) +*Figure 1: High-level architecture of the Item Stock exchange in Catena-X* + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +The sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in +this specification are non-normative. Everything else in this specification is normative. The key +words **MAY** , **MUST** , **MUST NOT** , **OPTIONAL** , **RECOMMENDED** , **REQUIRED** , +**SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in [BCP 14] +[[RFC2119]](#62-non-normative-reference) [[RFC8174]](#62-non-normative-reference) when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove that they are conform with the Catena-X +standards. To validate that the standards are applied correctly, Catena-X employs Conformity +Assessment Bodies (CABs). The proof of conformity for a single semantic model is done according to +the general rules for proving the conformity of data provided to a semantic model or the ability to +consume the corresponding data. Furthermore participants agree to follow the normative language of +this standardization document and to implement the required API-Endpoints described in [Chapter 4](#4-application-programming-interfaces). + +### 1.4 EXAMPLES + +The following example shows a value-only JSON serialization of the "ItemStock" aspect model. It +represents a quantity of 20 pieces for an order position of a given material. + +```json +{ + "materialGlobalAssetId" : "urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df", + "positions" : [ { + "orderPositionReference" : { + "supplierOrderId" : "M-Nbr-4711", + "customerOrderId" : "C-Nbr-4711", + "customerOrderPositionId" : "PositionId-01" + }, + "allocatedStocks" : [ { + "isBlocked" : false, + "stockLocationBPNA" : "BPNA1234567890ZZ", + "lastUpdatedOnDateTime" : "2023-04-28T14:23:00.123456+14:00", + "quantityOnAllocatedStock" : { + "value" : 20.0, + "unit" : "unit:piece" + }, + "stockLocationBPNS" : "BPNS1234567890ZZ" + } ] + } ], + "direction" : "INBOUND" +} +``` + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +| **Name** | **Abrv.** | **Description** | +| --- | --- | --- | +| **Business Partner Number** | BPN | A BPN is the unique identifier of a partner within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Business Partner Number Legal Entity** | BPNL | A BPNL is the unique identifier of a partner legal entity within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Business Partner Number Site** | BPNS | A BPNS is the unique identifier of a partner site within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Business Partner Number Address** | BPNA | A BPNA is the unique identifier of a partner address within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Position** | | A position within an order defines the product and the quantity the supplier has to manufacture / supply for a customer. A single order may contain multiple positions for different products. | +| **Order** | | Request from a customer towards a supplier to manufacture / supply a given quantity of a specific product in a predefined time frame. | +| **Allocated Stock** | | The already manufactured and not yet been used products, components or material. They are allocated to a specific customer based on the orders made by the latter and are either still in the supplier's warehouse or already in the customer's warehouse. | +| **Provider** | | The party providing the *Item Stock* data.In the context of the *Item Stock* exchange this is:
    - the supplier for *Item Stock* of direction OUTBOUND
    - the customer for *Item Stock* of direction INBOUND. | +| **Consumer** | | The party requesting and consuming the *Item Stock* data provided by the provider. In the context of the *Item Stock* exchange this is:
    - the supplier for *Item Stock* of direction OUTBOUND
    - the customer for *Item Stock* of direction INBOUND. Additional terminology used in this standard can be looked up in the glossary on the association homepage. | +| **Stock Location** | | The physical location of a stock specified by its corresponding BPNS and BPNA. More information on BPN/S/A is provided in [[CX-0010]](#61-normative-references). | +| **Customer** | | The recipient of products ordered from / manufactured by a supplier. | +| **Supplier** | | The supplier / manufacturer of a product. | +| **Stock** | | Two way direction of material on stock:
    - One can have a stock of material which is ready for delivery to customers
    - One can have a stock of material which can be used for the own production | +| **Material** | | The term material is used as a catalogue item in the meaning of the Industry Core Part Type ([[CX-0126]](#61-normative-references)). Whenever referring to material also products, components or items are considered. Semi-finished goods are not intended to be covered. | +| **Production Output** | | The output quantity in a defined period of time for a component or material. | +| **Digital Twin** | DT | Digital representation of an asset that provides data on aspects of the represented data following [[CX-0002]](#61-normative-references). | +| **decentralized Digital Twin Registry** | dDTR | Component providing registration and discovery API implementations following [[CX-0002]](#61-normative-references). Sometimes referred to without the "decentralized" BUT in Catena-X those are always decentralized. | +| **Asset Administration Shell** | AAS | Technical concept for Digital Twins consisting of different standards. Application in Catena-X is described in Digital Twins in Catena-X standard ([[CX-0002]](#61-normative-references)) | +| **Shell Descriptor** | | Technical concept of the AAS API describing metadata of an Asset Administration Shell representing a Digital Twin. It holds identification information and metadata about which submodels are available and where to get the data from (see [[CX-0002]](#61-normative-references), IDTA-01002-3-0). There may exist multiple Shell Descriptor for the same represented Asset (see [[CX-0126]](#61-normative-references)). | +| **Submodel Descriptor** | | Technical concept of the AAS API describing metadata of Submodels within a Shell Descriptor (Asset Administration Shell) (see [[CX-0002]](#61-normative-references), IDTA-01002-3-0). | +| **Specific Asset Ids** | | Identifiers of the Shell Descriptor (Asset Administration Shell) that refer to common identification data for an asset/material at hand e.g., manufacturer part Id. Common specific asset ids used for identification are described in Industry Core Part Type Standard (see [[CX-0126]](#61-normative-references)). | +| **Asset Administration Shell Identifier** | AAS ID | Also referred to as Shell Descriptor ID, is the technical identifier of the Shell Descriptor. | +| **Global Asset Id** | | Also referred to as Catena-X ID, is the Catena-X identifier for assets represented by Digital Twins (see [[CX-0126]](#61-normative-references)). | +| **Aspect** | | A domain-specific view on information and functionality associated with a specific Digital Twin with a reference to a concrete Aspect Model (see [[CX-0002]](#61-normative-references)). Within Catena-X, an aspect is formally described using the Semantic Aspect Meta Model (see [[CX-0003]](#61-normative-references)). | +| **Semantic Id** | | Identifier including namespace to specify the semantic description of submodels using the Semantic Aspect Meta Model (SAMM). It allows partners to know the exact data format and semantics when e.g., browsing catalogs (see [[CX-0003]](#61-normative-references)). | +| **Data Space Protocol** | DSP | A set of specifications designed to facilitate interoperable data sharing between entities governed by usage control and based on Web technologies. These specifications define the schemas and protocols required for entities to publish data, negotiate Agreements, and access data as part of a Dataspace. It is governed by the International Data Spaces Association. Connectors compliant to [[CX-0018]](#61-normative-references) support the Data Space Protocol. | +| **Shared Asset Approach** | | Digital twin pattern in which each party has a twin for the same asset (Part Type). They share the same identification data in terms of specific asset ids and global asset id. The digital twins do have different technical identifiers. | + +*Table 1: Terminology Item Stock Standard* + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 "ITEM STOCK" + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +The following Catena-X standards are prerequisites for the implementation of this standard and therefore +**MUST** be considered / implemented by the relevant parties specified in each of them. + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0001]](#61-normative-references) | EDC Discovery API | 1.0.2 | +| [[CX-0002]](#61-normative-references) | Digital Twins in Catena-X | 2.2.0 | +| [[CX-0003]](#61-normative-references) | SAMM Aspect Meta Model | 1.1.0 | +| [[CX-0006]](#61-normative-references) | Registration and initial onboarding | 2.0.0 | +| [[CX-0010]](#61-normative-references) | Business Partner Number (BPN) | 2.0.0 | +| [[CX-0018]](#61-normative-references) | Dataspace Connectivity | 3.0.0 | +| [[CX-0126]](#61-normative-references) | Industry Core Part Type | 2.0.0 | + +*Table 2: List of mandatory standards* + +The usage of this standard may be complemented with the following Catena-X standards to further extend +the range of shortage prevention possibilities: + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0118]](#61-normative-references) | Delivery Information Exchange | 2.0.0 | +| [[CX-0120]](#61-normative-references) | Short-term Material Demand Exchange | 2.0.0 | +| [[CX-0121]](#61-normative-references) | Planned Production Output Exchange | 1.0.0 | +| [[CX-0145]](#61-normative-references) | Days of Supply Exchange | 1.0.0 | +| [[CX-0146]](#61-normative-references) | Supply Chain Disruption Notifications | 1.0.0 | + +*Table 3: List of* *non-mandatory* *complementary standards* + +#### 2.1.2 DATA REQUIRED + +No additional data requirements. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### CONVENTIONS FOR USE CASE POLICY IN CONTEXT DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization +of data within the Catena-X use cases has been outlined. A set of specific policies on data offering +and data usage level detail the conditions under which data may be accessed, shared, and used, +ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data +usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository [[CX-ODRL]](#62-non-normative-references). This document provides in-depth explanations of the + terms and conditions applied to data access and utilization, ensuring that all engagement with our data + is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. + Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +###### ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for +members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, +Data Provider maintains control over its anti-trust obligations when sharing certain data. In +particular, Data Provider may apply Access Policies to restrict access to a particular data offer +for only one Participant identified by a specific business partner number. + +- Membership +- BPNL + +###### ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use +the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are +provided via the ODRL policy repository [[CX-ODRL]](#62-non-normative-references). + +##### REMINDER OF ANTITRUST + +Notice and/or acknowledgement concepts to raise awareness of antitrust issues during use of this standard +are **RECOMMENDED**, for example through the implementation of a help desk or pop-up info. + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +This standard builds upon the Industry Core Part Type [[CX-0126]](#61-normative-references) and the Digital Twins in +Catena-X [[CX-0002]](#61-normative-references) standards. It follows the following design patterns: + +- Usage of Digital Twins as shared assets to follow a pull approach for data. +- Usage of the specific asset IDs and further identification data for the Digital Twin for the Part Type + (see [[CX-0126]](#61-normative-references)). +- Provisioning of the *PartTypeInformation* on supplier side (see [[CX-0126]](#61-normative-references)). + +Because both parties may provide data regarding different aspects of the same Part Type Twin, they need +to use the same identification data to pinpoint it. + +- The supplier of the part has a Digital Twin representation and is then able to offer + *Item Stock* data to customers. +- The customer, who orders or uses the part, has a Digital Twin representation to offer + *Item Stock* data to a supplier. +- Both twins refer to the same asset and provide complementary information. They share the same + identification data in two partners' context. + - The supplier + - **MUST** create the Digital Twin first. + - **MUST** generate the Catena-X ID and ensure that the customer-specific asset IDs and submodel + descriptors are only accessible by the specific customer. + - **MAY** use the Digital Twin for multiple customers. + - The customer + - **MUST** create one Digital Twin per supplier. + - **MUST** use the Catena-X ID generated by the supplier. + +The definition of identification data (Catena-X ID, Asset Administration Shell ID, specific asset ID) +**MUST** follow the Industry Core Part Type [[CX-0126]](#61-normative-references). Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for further details. + +> ***Note:*** The Part Type Twin's data is considered sensitive. Data providers **MUST** implement appropriate +measures ensuring that competitors-specific asset IDs and/or information about submodels is accessible +only to the data consumers it concerns, but not to their competitors. + +Figure 2 shows how the shared asset approach is realized. The orange lines show which submodels belong +to the respective AAS. All *Item Stock* specific submodels are bound to the specific +Part Type's context e.g., meaning that the *Item Stock* aspect is described for the specific +catalog item on supplier and customer side represented by the AASs. The orange submodels are the +submodels used within this standard's context. The grey submodels are used within the Industry Core +[[CX-0126]](#61-normative-references)(*PartTypeInformation, SingleLevelBomAsPlanned, SingleLevelUsageAsPlanned*). +The blue dashed lines show the references between DTs based on Catena-X UUIDs and BPNL information that +may be resolved by the Item Relationship Service (see [[CX-0126]](#61-normative-references)). + +![Figure 2: Conceptual levels of provisioning digital twins in the shared asset approach.](./assets/Figure_2.svg) +*Figure 2: Conceptual levels of provisioning digital twins in the shared asset approach.* + +Figure 2 details two conceptual levels: + +- The Asset level contains the asset (Industry Core Part Type) represented by a Digital Twin. + The latter is provisioned as an Asset Administration Shell (AAS) within the decentralized Digital + Twin Registry (dDTR) of the data provider (supplier or customer). +- The Submodel level represents the actual information that are held by a Digital Twin (DT). Those + submodels follow the respective definition of the in Semantic Aspect Meta Model (SAMM) format + (see [Chapter 3](#3-aspect-models)). The dDTR only holds meta-information about the Submodel + (e.g. kind of submodel via semantic ID or connector endpoint information). + +## 3 ASPECT MODELS + +> *This section is normative* + +### 3.1 "ITEM STOCK" ASPECT MODEL + +#### 3.1.1 INTRODUCTION + +This section describes the "ItemStock" semantic model used in the Catena-X network. For the complete +semantics and detailed description of its properties refer to the SAMM model in [Chapter 3.1.5.1](#3151-rdf-turtle). + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the +"semantic-driven workflow" to create a submodel template specification [[SMT]](#62-non-normative-references). + +This aspect model is written in SAMM 2.0.0 as a modeling language conformant to [[CX-0003]](#61-normative-references) as +input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to [[CX-0003]](#61-normative-references). + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +> `urn:samm:io.catenax.item_stock:2.0.0` + +This identifier **MUST** be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The RDF turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional +file formats and serializations. It can be found under the following link: + +> [https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.item\_stock/2.0.0/ItemStock.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.item_stock/2.0.0/ItemStock.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of +other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template +or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload +of the Asset Administration Shell for the API operation *"GetSubmodel"*. + +##### 3.1.5.3 AASX + +An AASX file **MUST** be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to [[SMT]](#62-non-normative-references). + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +### 4.1 API USED TO EXCHANGE "ITEM STOCK" INFORMATION + +As described in [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids) this standard builds upon the [[CX-0002]](#61-normative-references) Digital Twins in Catena-X +and [[CX-0126]](#61-normative-references) Industry Core Part Type standards. Therefore, the APIs provided by the Digital Twin +standard are combined with the part identification defined in the Industry Core standard. This chapter +defines how the aforementioned standards and the [[CX-0018]](#61-normative-references) +standard **MUST** be used to facilitate the provisioning of *Item Stock* data. The +usage of the Discovery Services defined in [[CX-0001]](#61-normative-references), [[CX-0053]](#61-normative-references) is not mandatory, +because this standard assumes an already existing business relationship between the involved parties. + +The sequence diagram in *Figure 3* provides an overview of the interactions required to register the +Part Type Twin following the shared asset approach. + +- Steps 1 & 2: Register the dDTR access for the partner at the connector +- Steps 3 & 4: When using the repository pattern, create the submodel (and twin) +- Steps 5 & 6: Register the submodel endpoint for the partner at the connector +- Steps 7 & 8: Register or update the twin Shell Descriptor relying on the registered Connector asset + for the submodel endpoint and the identification data of the partners. + +> ***Note:*** This sequence diagram is simplified and does not cover the generation of the Part Type Twin +on supplier side and the handling of the identification data needed. Both partners need to create a +Part Type Twin of the shared asset as well as provide *Item Stock* data. + +![Figure 3: Flow to create and register a digital twin](./assets/Figure_3.svg) +*Figure 3: Flow to create and register a digital twin* + +The sequence diagram in Figure 4 provides an overview of the interactions required when a customer +(acting as data provider) provisions *Item Stock* data to a supplier (acting as data consumer). + +The flow "*Supplier reads (updated) Submodel from Customer*" visualizes the sequence of calls when consuming data: + +- Steps 3 - 8: Contract dDTR usage in the connector. +- Steps 9 - 12: Lookup the Industry Core Part Type Twin for a Part Type based on the common identification data. +- Steps 13 - 18: Read the Shell Descriptor of the Industry Core Part Type Twin to extract the *Item Stock* + submodel endpoint (registered at the connector). +- Steps 19 - 24: Contract the *Item Stock* data usage in the connector. +- Steps 25 - 29: Consume and use the *Item Stock* data. + +![Figure 4: Flow to look up a digital twin and get a submodel.](./assets/Figure_4.svg) +*Figure 4: Flow to look up a digital twin and get a submodel.* + +> ***Note:*** Depending on the use of repository patterns and the design of the Digital Twins, the data +may be updated manually in the Submodel endpoint. + +#### 4.1.1 CONNECTOR DATA ASSET STRUCTURE + +The endpoints for the dDTR and the Submodel Endpoint **MUST** be made available BUT they **MUST NOT** +be directly called data consumer. Rather, for access to dDTRs and Submodels, there **MUST** be contracts +negotiated in accordance with the DSP. Therefore, the endpoints **MUST** be offered as connector data +assets. To make these assets easily identifiable in the connector's catalog, each asset **MUST** be +configured with a set of properties as described in the corresponding sections below. + +The following table provides an overview of the connector data assets that the parties **MUST** offer +to be able to provision and/or consume *Item Stock* data. + +| **Party** | **REQUIRED** | **Asset** | **Purpose** | +| --- | --- | --- | --- | +| Provider | Yes | "Digital Twin Registry" | Allows a consumer to query for Part Type Twins and their *Item Stock* submodels. | +| Provider | Yes | "Submodel Item Stock" | Allows a consumer to read actual *Item Stock* information related to a Part Type Twin. | +| Consumer | Yes | "Digital Twin Registry" | Allows a consumer to query for Part Type Twins and their *Item Stock* submodels. | +| Consumer | Yes | "Submodel Item Stock" | Allows a consumer to read actual *Item Stock* information related to a Part Type Twin. | + +*Table 4: Connector data assets* + +In the sections below the asset definitions of the two different kinds of assets are defined. + +##### CONNECTOR DATA ASSET STRUCTURE FOR "Digital Twin Registry" + +To allow partners to find the "Item Stock" data for a specific Industry Core Part Type Twin, +the provider **MUST** register a connector data asset (see details in [[CX-0018]](#61-normative-references)) specifying the address +of the Digital Twin Registry of the provider (see [[CX-0002]](#61-normative-references)). + +The data asset **MUST** be configured with the set of properties as defined in the table below. + +| **Object** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***@id*** | Identifier of the asset | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. | +| properties | [**http://purl.org/dc/terms/type**](http://purl.org/dc/terms/type) | Defines the "Digital Twin Registry" according to the Catena-X taxonomy. | **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#DigitalTwinRegistry"}` to allow filtering the data assets catalog for the respective "Digital Twin Registry". | +| properties | [**https://w3id.org/catenax/ontology/common#version**](https://w3id.org/catenax/ontology/common#version) | The version of the standard defining the implemented API of the "Digital Twin Registry" | **MUST** correspond to the version of the standard defining the Interfaces of the "Digital Twin Registry". The value **MUST** be set to `"3.0"` for "Digital Twin Registries" used by this standard. | +| dataAddress | **@type** | Type of the DataAddress node. | **MUST** be set to `"DataAddress"`. | +| dataAddress | ***baseUrl*** | Defines the HTTPS endpoint of the corresponding "Digital Twin Registry Endpoint". | The `{{ DIGITAL_TWIN_REGISTRY_ENDPOINT }}` refers to an URL under which the API of the "Digital Twin Registry" endpoint is available. HTTPS transport protocol **MUST** be used. | +| dataAddress | ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body | **SHOULD** be set to `"false"` to not allow the API endpoint to receive a HTTPS body via the HTTPS request. | +| dataAddress | ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method | **SHOULD** be set to `"false"` to only allow the API endpoint to receive GET requests. | +| dataAddress | ***proxyPath*** | Defines whether the endpoint allows to proxy paths for the URL | **MUST** be set to `"true"` to allow the API endpoint to receive appended paths of the HTTPS request. | +| dataAddress | ***type*** | Defines the type of data plane extension handling the data exchange | **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. | + +*Table 5: Connector data assets request properties* + +Additionally security identification information **MAY** be added to secure the "Decentralized Digital Twin Registry". + +When searching the Catalog of a provider, a consumer **SHOULD** use the following properties AND +their values to identify the Data Asset specifying "Digital Twin Registry". In the connector Data Asset +descriptions the API version valid for this standard is mentioned for the property +[`https://w3id.org/catenax/ontology/common#version`](https://w3id.org/catenax/ontology/common#version). The requester of a Data Asset **MUST** be +able to handle multiple Data Asset for this endpoint, being differentiated only by the version. +The requester **SHOULD** choose the Data Asset set with the highest compatible version number implemented +by themselves. If the requester cannot find a compatible version with their own, the requester **MUST** +terminate the data transfer. + +| **Property** | **Value** | +| --- | --- | +| http://purl.org/dc/terms/type | `{"@id": "https://w3id.org/catenax/taxonomy#DigitalTwinRegistry"}` | + +*Table 6: Connector data assets request properties values.* + +An example connector data asset definition is given below. + +>**Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "http://purl.org/dc/terms/" + }, + "@id": "{{CONNECTOR_ASSET_ID}}", + "properties": { + "dct:type": {"@id": "cx-taxo:DigitalTwinRegistry"}, + "cx-common:version": "3.0" + }, + "privateProperties": { + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ DIGITAL_TWIN_REGISTRY_ENDPOINT }}", + "proxyQueryParams": "true", + "proxyBody": "false", + "proxyPath": "true", + "proxyMethod": "false", + } +} +``` + +##### CONNECTOR DATA ASSET STRUCTURE FOR "Submodel" + +To allow partners to receive the "Item Stock" data as defined in [Chapter 3](#3-aspect-models), +the provider **MUST** register a connector data asset (see details in[[ CX-0018]](#61-normative-references)) specifying the +address of the submodel endpoint (see [[CX-0002]](#61-normative-references)) providing the actual data. + +The data asset **MUST** be configured with the set of properties as defined in the table below. + +| **Object** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***@id*** | Identifier of the asset | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. | +| properties | [**http://purl.org/dc/terms/type**](https://purl.org/dc/terms/type) | Defines the "Submodel API" according to the Catena-X taxonomy. | **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#Submodel"}` to allow filtering the data assets catalog for the respective "Submodel API". | +| properties | [**https://admin-shell.io/aas/3/0/HasSemantics/semanticId**](https://admin-shell.io/aas/3/0/HasSemantics/semanticId) | The semantic identifier of the "Item Stock" SAMM. | **MUST** be set to `{"@id": "urn:samm:io.catenax.item_stock:2.0.0#ItemStock"}` to externally define how the Submodel must be interpreted. **MUST NOT** be set, if different submodels may be returned by this API. | +| properties | [**https://w3id.org/catenax/ontology/common#version**](https://w3id.org/catenax/ontology/common#version) | Version of the Submodel Interface Specification | **MUST** be set to `"3.0"` in accordance to [[CX-0002]](#61-normative-references). | +| dataAddress | **@type** | Type of the DataAddress node. | **MUST** be set to `"DataAddress"`. | +| dataAddress | ***baseUrl*** | Defines the HTTPS Submodel endpoint provisioning the *Delivery Information* data | The `{{ SUBMODEL_ENDPOINT }}` refers to an URL under which the Submodel API Endpoint ([[CX-0002]](#61-normative-references)) is available to provide the "Item Stock" . HTTPS transport protocol **MUST** be used. | +| dataAddress | ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body | **SHOULD** be set to `"false"` to not allow the API endpoint to receive a HTTPS body via the HTTPS request. | +| dataAddress | ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method | **SHOULD** be set to `"false"` to only allow the API endpoint to receive GET requests. | +| dataAddress | ***proxyPath*** | Defines whether the endpoint allows to proxy paths for the URL | **MUST** be set to `"true"` to allow the API endpoint to receive appended paths of the HTTPS request. Setting this parameter depends on the implementation of the submodel lookup. | +| dataAddress | ***type*** | Defines the type of data plane extension handling the data exchange | **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. | + +*Table 7: Connector data assets request properties* + +Additionally security identification information **MAY** be added to secure the "Submodel API". + +When searching the data assets catalog of a provider, a consumer **SHOULD** use the assetId previously +determined via `subprotocolBody` of the SubmodelDescriptor's endpoint definition of subprotocol type "DSP". +Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for the definition of the `subprotocolBody`. + +| **Property** | **Value** | +| --- | --- | +| [https://w3id.org/edc/v0.0.1/ns/id](https://w3id.org/edc/v0.0.1/ns/id) | `{{CONNECTOR_ASSET_ID}}` specified in the DSP endpoint of the SubmodelDescriptor (see [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition)) | + +*Table 8: Connector data assets request properties values* + +An example connector data asset definition is given below. + +>**Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "http://purl.org/dc/terms/", + "aas-semantics": "https://admin-shell.io/aas/3/0/HasSemantics/" + }, + "@id": "{{CONNECTOR_ASSET_ID}}", + "properties": { + "dct:type": {"@id": "cx-taxo:Submodel"}, + "cx-common:version": "3.0", + "aas-semantics:semanticId": {"@id": "urn:samm:io.catenax.item_stock:2.0.0#ItemStock"} }, + "privateProperties": { + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ SUBMODEL_ENDPOINT }}", + "proxyQueryParams": "false", + "proxyBody": "false", + "proxyPath": "true", + "proxyMethod": "false", + } +} +``` + +#### 4.1.2 INDUSTRY CORE PART TYPE TWIN REGISTRATION AND DEFINITION + +##### 4.1.2.1 SHELL DESCRIPTOR REGISTRATION + +To allow partners to receive the actual "*Item Stock*" data as defined in [Chapter 3](#3-aspect-models), +the provider **MUST** register a Shell Descriptor in the dDTR (see [[CX-0002]](#61-normative-references)) so that a partner: + +- May lookup the Industry Core Part Type Twin based on known identification data. +- May identify the connector endpoint providing access to the "Item Stock" submodel data. + +The Shell Descriptors represent each an Industry Core Part Type Twin and **MUST** follow the rules as defined +in [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids). + +The Shell Descriptor **MUST** be configured with the set of properties as defined in the table below. + +| **Object in ShellDescriptor** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***id*** | Defines the technical ID of the Asset Administration Shell representing a partner's twin. | **MUST** be unique following Industry Core Part Type standard ([[CX-0126]](#61-normative-references)) and is a technical Id randomly assigned as multiple Part Type Twins may be created for one Part Type. E.g. this number differs for the twins created at supplier and customer side. | +| | ***globalAssetId*** | Defines the Catena-X ID of the twin. | **MUST** be aligned with the partner's material. When referring to the same Part Type Twin, the same number **MUST** be used (see [[CX-0126]](#61-normative-references)). | +| | **specificAssetIds** | Identifiers that may be used to lookup Part Type Twins. | **MUST** be set to according to the Industry Core Part Type standard ([[CX-0126]](#61-normative-references)). See *Table 10* for respective specific asset IDs. The `"customerPartId"` **MUST** be set by Customers and **SHOULD** be set by Suppliers. | +| submodelDescriptor | **id** | Technical identifier of a SubmodelDescriptor. | **MUST** be set to a unique identifier. | +| submodelDescriptor | **semanticId** | The semantic identifier of the "Item Stock" SAMM. | **MUST** be set to `{ "type": "ExternalReference", "keys": [{ "type": "GlobalReference", "value": "urn:samm:io.catenax.item_stock:2.0.0#ItemStock" }] }` to externally define how the Submodel must be interpreted. | +| submodelDescriptor > endpoint | **interface** | Defines the Submodel Interface [[CX-0002]](#61-normative-references) and the version. | **MUST** be set to `"SUBMODEL-3.0"` to rely on current specification. | +| submodelDescriptor > endpoint > protocolInformation | **href** | Defines the direct link to the public API of the connector's data plane with a path that **SHOULD** be appended by the proxy, if needed. | **MUST** be set to the public API of the dataplane providing the data with the path appended to directly access the submodel. | +| submodelDescriptor > endpoint > protocolInformation | **subprotocol** | Defines the usage of the connector based on DSP to access and use the submodel. | **MUST** be set to `"DSP"` to define the connector endpoint of the subprotocol. | +| submodelDescriptor > endpoint > protocolInformation | **subprotocolBody** | Defines the asset id in the connector and the connector address to access and use the submodel. | **MUST** be set to `"id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}"` to provide the necessary information for contracting the submodel endpoint. Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for the definition of the asset of the subprotocolBody. | + +*Table 9: Properties relevant for the Shell Descriptor definition* + +When searching the submodel in the dDTR of a provider, a consumer **SHOULD** use the specific asset IDs +as defined in [[CX-0126]](#61-normative-references). Table 10 gives an overview of the specific asset IDs that the data provider +added to the ShellDescriptor so that the data consumer may find the Industry Core Part Type Twin. + +| **Specific Asset Id** | **Value** | +| --- | --- | +| digitalTwinType | "PartType". Set to identify twins compliant to the Industry Core Part Type (see [[CX-0126]](#61-normative-references)). | +| manufacturerId | Supplier / Manufacturer partner BPNL (see [[CX-0010]](#61-normative-references)) | +| manufacturerPartId | Supplier / Manufacturer partner identification number of the part. | +| customerPartId | Customer partner identification number of the part. | + +*Table 10: Specific asset IDs of Industry Core Part Type Twins proposed to be used to lookup a twin in the dDTR* + +The Shell Descriptor defines the metadata of the Industry Core Part Type Twin. The following example +Shell Descriptor represents a supplier's Shell Descriptor of a supplier who provides two customers access +to an "Item Stock" submodel. For further information on the creation of Part Type Twins, +refer to [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids). + +Following [[CX-0002]](#61-normative-references), when searching the data assets catalog of a provider, a consumer **SHOULD** +use the `assetId` determined via `subprotocolBody` of the SubmodelDescriptor's endpoint definition +of subprotocol type `"DSP"` of the Submodel Descriptor of interest. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "id": "{{TECHNICAL_TWIN_ID}}", + "globalAssetId": "{{MATERIAL_NUMBER_CX}}", + "idShort": "Semiconductor", + "specificAssetIds": [ + { + "name": "digitalTwinType", + "value": "PartType", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "manufacturerPartId", + "value": "{{MATERIAL_NUMBER_SUPPLIER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "manufacturerId", + "value": "{{SUPPLIER_BPNL}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "customerPartId", + "value": "{{MATERIAL_NUMBER_CUSTOMER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "customerPartId", + "value": "{{MATERIAL_NUMBER_OTHER_CUSTOMER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + } + ], + "submodelDescriptors": [ + { + "id": "e5c96ab5-896a-482c-8761-efd74777ca97", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.item_stock:2.0.0#ItemStock" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "{{SUPPLIER_CONNECTOR_DATAPLANE_PUBLIC_API}}/{{PATH_IF_NEEDED}}", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ] + }, + { + "id": "a6c96ab5-896a-482c-8761-efd74777ca99", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.item_stock:2.0.0#ItemStock" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "{{SUPPLIER_CONNECTOR_DATAPLANE_PUBLIC_API}}/{{PATH_IF_NEEDED}}", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ] + } + ] +} +``` + +##### 4.1.2.2 LOOKING UP A PART TYPE TWIN IN THE DDTR + +To query the dDTR of a data provider, after contracting the usage via the data provider's connector +(see [[CX-0018]](#61-normative-references)), the lookup API (see [[CX-0002]](#61-normative-references)) can be used relying on the specific +asset IDs defined by the Industry Core Part Type (see [[CX-0126]](#61-normative-references)) that can be seen in +Table 10 (table of shellDescriptorRegistration with specific asset IDs). + +An example call relying on all information is given in the code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{PARTNER_CONNECTOR_DATA_PLANE}}/lookup/shells?assetIds={"name":"digitalTwinType", "value": "PartType"},{"name":"manufacturerPartId", "value": "{{MATERIAL_NUMBER_SUPPLIER}}"},{"name":"manufacturerId", "value": "{{SUPPLIER_BPNL}}"},{"name":"customerPartId", "value": "{{MATERIAL_NUMBER_CUSTOMER}}"} +``` + +As a result identifiers of the ShellDescriptors will be returned. With this data, a data provider can +read the ShellDescriptor to extract the endpoint data of the data provider. An example is given in the +code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{PARTNER_CONNECTOR_DATA_PLANE}}/shell-descriptors/{{AAS_IDENTIFIER}} +``` + +##### 4.1.2.3 FETCHING SUBMODEL DATA + +To fetch the *Item Stock* Submodel data at the submodel endpoint of a data provider, after +contracting the usage via the data provider's connector (see [[CX-0018]](#61-normative-references)), the submodel API (see [[CX-0002]](#61-normative-references)) +can be used. + +An example call relying on all information is given in the code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{HREF_PATH}}/$value +``` + +## 5 PROCESSES + +> *This section is normative* + +### 5.1 GENERAL INFORMATION ON THE USE OF ITEM STOCK + +A prerequisite to build up an *Item Stock* and allocate it to a specific customer or supplier is an +existing order / call-off (build-to-order). This standard, must not be used in case of building +stock without any allocation to a customer or supplier (build-to-stock). + +In contrast to the Demand and Capacity Management standard [[CX-0128]](#61-normative-references), this information relates to +short-term planning periods of 1-4 weeks. Accordingly, neither long-term planning nor strategic +planning is included in the scope. This means that only the current/actual *Item Stock* quantities +are transmitted in this standard. + +We distinguish between exactly two scenarios in multi sourcing. On the one hand, the exchange of +information from supplier to customer and, on the other hand, from customer to supplier. In both +scenarios, information must not be shared horizontally under any circumstances. This means that +the *Item Stock* in relation to other customers or suppliers must not be shared. + +The data exchange between the C-X participants refers to the direct business relationship among each +other. In the case of consignation, the warehouse is specified via the real location - the +customer/supplier site. In this case the allocated stock is not considered as taken and according to +our definition as not delivered (have not yet been shipped). + +### 5.2 ITEM STOCK PROVISIONING WITHIN SINGLE SOURCING AND SINGLE CUSTOMER SCENARIOS + +#### 5.2.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. The common definitions are found in +[Chapter 1.5](#15-terminology). This section describes respective scenarios. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Customer** | The customer acts as the data consumer and provider in this standard. | A business partner that procures items from its supplier and requests information about its allocated item stock information. The customer provides information about its own stock in relation to the assigned supplier. | +| **Supplier** | The supplier acts as the data consumer and provider in this standard. | A business partner that supplies items to a customer. The supplier requests the allocated item stock from the customer and provides the item stock already produced for the customer. Regardless of the site in which the item stock is located. | + +*Table 11: Actors and roles 1* + +#### 5.2.2 PROCESS REPRESENTATION + +Information about the item stock is exchanged between the customer and the supplier in both +directions - that means the Information is exchanged from the customer to the supplier and vice +versa. The representative example explains which item stock information must be exchanged. +The actual and not the planned data must be queried and transmitted. The following example shows +a bottleneck situation in which the supplier has a complete loss of production for one day. This +affects his ability to fulfill the demand for the next day, so he delivers only 200 pieces. Due to +the given just-in-time scenario, the situation can only be partially covered by the supplier's own +item stock. The exchange via item stock thus shows the consequences at an early stage and the +customer can adjust its production planning. + +> Note: The item stock information for supplier and customer refer always to the value at the end +> of the business day. The supplier's production output is the value at the end of the business day +> and is used for delivery and stock build-up on the following day. + +##### Recommended procedure in case of single sourcing with information about Item Stock from customer to supplier and vice versa + +> Note: In this example the calculations are as follows: +> *Item Stock Customer (day n) = Item Stock Customer (day n-1) + Delivery (day n) - Consumption (day n);* +> *also: Delivery (day n) = Production Output (day n-1) - Item Stock Supplier (day n)* + +![Table 12: Single source example](./assets/Table_12.svg) +*Table 12: Single source example* + +> Note: In this standard, only current/actual *Item Stock* quantities are transmitted. + +This procedure takes into consideration the following aspects: + +- The customer may share with the supplier the following information on a daily basis: + - Information on the volumes called off by the customer + - the supply volumes delivered in response to this call-off (covered by [[CX-0118]](#61-normative-references)) + - the consumption allocated to the supplier's products (covered by [[CX-0120]](#61-normative-references)) + - the actual *Item Stock* of its products at the customer's site (covered in this standard) + +- The supplier may share with the customer the following information on a daily basis: + - the supply volumes delivered in response to this call-off (covered by [[CX-0118]](#61-normative-references)) + - the production output allocated to the customer's products (covered by [[CX-0121]](#61-normative-references)) + - the actual *Item Stock* of its products at the supplier's site (covered in this standard) + +### 5.3 ITEM STOCK PROVISIONING WITHIN MULTI SOURCING SCENARIOS + +#### 5.3.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. The common definitions are found in +[Chapter 1.5](#15-terminology). This section describes respective scenarios. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Customer** | The customer acts as the data provider in this standard. | A business partner that procures items from its supplier and provides information about its own stock in relation to the assigned supplier. | +| **Supplier A** | The supplier A acts as the data consumer in this standard. | A business partner that supplies items to a customer and requests the allocated item stock from the customer. Regardless of the warehouse in which the item stock is located. Supplier A has no knowledge of the business relationship between the customer and Supplier B. | +| **Supplier B** | The supplier B acts as the data consumer in this standard. | A business partner that supplies items to a customer and requests the allocated item stock from the customer. Regardless of the site in which the item stock is located. Supplier B has no knowledge of the business relationship between the customer and Supplier A. | + +*Table 13: Actors and roles 2* + +#### 5.3.2 PROCESS REPRESENTATION + +Multi-sourcing is a common scenario in the field. Suppliers usually supply several customers with the +same material/component. And customers purchase the same component types from different suppliers. +Because of that, in the case of multi-sourcing, when there is no possibility of differentiating the +items received from different suppliers (i.e. by using different item numbers for each supplier), +the customer must be aware that competition sensitive information from one supplier must not +be shared with other suppliers. After evaluating different alternatives, the following procedure is +the one recommended from the item stock standardization team and legal advisors to all users in +order to ensure a compliant exchange of information from customer to suppliers in the case of +multi-sourcing. + +In this example, the shortage situation occurs at supplier B on days 5 and 6 and at supplier A on +days 8 and 9. To alleviate the shortage, a larger quantity is requested from supplier A on day 5 and +from supplier B on day 9. This ensures that the bottleneck situation has no effect on the customer's +production. + +##### Recommended procedure in case of multi-sourcing with information exchange from customer to supplier: quoting consumption, keeping track of deliveries + +> Note 1: in this example Item Stock A and Item Stock B make reference to the Item stock at the customer's +> site that is allocated respectively to supplier A and B. + +> Note 2: in this example the calculations are as follows (example on Supplier A, also applies to Supplier B): +> *Item Stock A (day n) = Item Stock A (day n-1) + Delivery A (day n) - Allocated consumption A (day n);* +> *if Stock B (day n) ≤ 0 then Allocated consumption A (day n new) = Allocated consumption A (day n old)+ |Stock B (day n)|* +> *and Stock B (day n new)= 0* + +> Note 3: This quote is only necessary in case keeping track of the parts supplied by different suppliers +> is not possible (i.e. by using different item numbers for each supplier) + +![Table 14: Multi-source customer example](./assets/Table_14.svg) +*Table 14: Multi-source customer example* + +> Note: In this standard, only current/actual *Item Stock* quantities are transmitted. + +This procedure (*quoting consumption, keeping track of deliveries*) takes in consideration the following aspects: + +- The customer may share with the supplier A the following information on a daily basis: + - Information on the volumes called off by the customer but only in relation to the specific supplier ("Allocated call off A") + - the supply volumes delivered in response to this call-off ("Delivery A") (covered by [[CX-0118]](#61-normative-references)) + - the consumption allocated to the supplier's products ("Allocated consumption A") (covered by [[CX-0120]](#61-normative-references)) + - the actual *Item Stock* at the customer ("Item Stock A"), (covered in this standard) + +- The customer must not share the following information with the supplier and the supplier must not be able to derive this information from the information available to it: + - Capacity data of other suppliers, + - the overall volumes called off by the customers ("Call off customer TOTAL"), + - information on the volumes called off by the customer in relation to another supplier ("Allocated call off B"), + - the supply volumes delivered by another supplier ("Delivery B"), + - the overall consumption delivered by all suppliers ("Consumption customer TOTAL"), + - the consumption allocated to another supplier ("Allocated consumption B"), + - the customer's total *Item Stock* ("Item stock customer TOTAL"), (covered in this standard) + - the *Item Stock* from another supplier at the customer ("Item Stock B"). (covered in this standard) + +> Note: For Supplier B, the same procedure applies in reverse. + +### 5.4 ITEM STOCK PROVISIONING WITHIN MULTI CUSTOMER SCENARIO + +#### 5.4.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. The common definitions are found in +[Chapter 1.5](#15-terminology). This section describes respective scenarios. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Customer A** | The customer acts as the data consumer in this standard. | A business partner that procures items from its supplier and requests information about the supplier's allocated item stock information. | +| **Customer B** | The customer acts as the data consumer in this standard. | A business partner that procures items from its supplier and requests information about the supplier's allocated item stock information. | +| **Supplier** | The supplier acts as the data provider in this standard. | A business partner that supplies items to more than one customer. It provides the item stock already produced for the customer. Regardless of the site in which the item stock is located. | + +*Table 15: Actors and roles 3* + +#### 5.4.2 PROCESS REPRESENTATION + +In this scenario, two customers procure the same item from one supplier. In addition to the *Item +Stock*, the call-offs and the actual delivery quantity are displayed once for each day. There is a +distribution of the supplier's total production output in a ratio of 1:3, i.e. each customer +receives 1/3 of the planned production quantity and 1/3 is left in the supplier's warehouse. The +information transmitted must be separated for each customer. The information must not be +shared horizontally under any circumstances. This means that the *Item Stock* in relation to other +customers must not be shared. On day 5 and 6, a complete production downtime occurs at the +supplier. The supplier now supplies its customers from its own stock and transmits the *Item Stock* +information in the corresponding ratio. From day 7, production continues as planned. + +##### Recommended procedure in case of multi customer with single sourcing + +![Table 16: single supplier to multi customer example](./assets/Table_16.svg) +*Table 16: single supplier to multi customer example* + +A suitable measure must be found for the allocation and provision of information. +We recommend the use of the ratio or the quoting of the call-off. + +> Note: In this standard, only current/actual *Item Stock* quantities are transmitted. + +This procedure takes in consideration the following aspects: + +- The customer may share with the supplier the following information on a daily basis: + - Information on the volumes called off by the customer + - the supply volumes delivered in response to this call-off (covered by [[CX-0118]](#61-normative-references)) + - the consumption allocated to the supplier's products (covered by [[CX-0120]](#61-normative-references)) + - the actual *Item Stock* of its products at the customer's site (covered in this standard) + +- The supplier may share with the customers the following information on a daily basis: + - the supply volumes delivered in response to the customer's call-off (covered by [[CX-0118]](#61-normative-references)) + - the production output allocated to the customer's material or products (covered [[CX-0121]](#61-normative-references)) + - the actual *Item Stock* of its material or products at the supplier site (covered in this standard) + +- The supplier must not share the following information with the customer and the customer must not otherwise be able to derive this information from the information available to it: + - Capacity and delivery data of another customer, + - the overall volumes called off by the customers, + - the supply volumes delivered to another customer, + - the supplier's total *Item Stock* (covered in this standard), + - the supplier *Item Stock* allocated for another customer (covered in this standard) + +### 5.5 ITEM STOCK USE OF ASSIGNMENT TO SITES AND ADDRESSES + +#### 5.5.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. The common definitions are found in +[Chapter 1.5](#15-terminology). This section describes respective scenarios. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Customer** | The customer acts as the data consumer and provider in this standard. | Is a business partner that procures items from its supplier and requests information about its allocated item stock information. The customer provides information about its own stock in relation to the assigned supplier. | +| **Supplier** | The supplier acts as the data consumer and provider in this standard. | Is a business partner that supplies items to a customer. It requests the allocated item stock from the customer and provides the item stock already produced for the customer. Regardless of the site in which the item stock is located. | + +*Table 17: Actors and roles 4* + +#### 5.5.2 PROCESS REPRESENTATION + +The distinction between customer and supplier locations must be made via the unique breakdown to +BPNS and BPNA. This means that a legal entity can have several sites and addresses with its BPNL and +these are mapped via the BPNS and BPNA. Why is this distinction used? A location is always assigned +to the customer and supplier via the site with its BPNS. However, a site can have several addresses, +e.g. for delivery. Furthermore, additional addresses can belong to a site via consignation and +external warehouses. It is therefore also possible that, for example, the customer address is the +same as the address of the external warehouse which is assigned to the supplier. In addition, the +delivery information may also be enriched in this way, because a delivery time results from the +respective location with its address. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [CX-0001] | EDC Discovery API | 1.0.2 | +| [CX-0002] | Digital Twins in Catena-X | 2.2.0 | +| [CX-0003] | SAMM Aspect Meta Model | 1.1.0 | +| [CX-0006] | Registration and initial onboarding | 2.0.0 | +| [CX-0010] | Business Partner Number (BPN) | 2.0.0 | +| [CX-0018] | Dataspace Connectivity | 3.0.0 | +| [CX-0053] | Discovery Finder and BPN Discovery Service APIs | 1.1.0 | +| [CX-0118] | Delivery Information Exchange | 2.0.0 | +| [CX-0120] | Short-term Material Demand Exchange | 2.0.0 | +| [CX-0121] | Planned Production Output Exchange | 2.0.0 | +| [CX-0126] | Industry Core Part Type | 2.0.0 | +| [CX-0128] | Demand and Capacity Management | 2.0.0 | +| [CX-0145] | Days of Supply Exchange | 1.0.0 | +| [CX-0146] | Supply Chain Disruption Notifications | 1.0.0 | + +### 6.2 NON-NORMATIVE REFERENCE + +> *This section is non-normative* + +| **Context** | **Link** | +| --- | --- | +| [CX-OMW] | Catena-X Operating Model Whitepaper. Download from: [https://catena-x.net/fileadmin/\_online\_media\_/CX\_Operating\_Modelv2.1_final.pdf](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf) | +| [CX-ODRL] | Catena-X ODRL Profile repository: https://github.com/catenax-eV/cx-odrl-profile | +| [RFC2119] | Bradner, S. Key words for use in RFCs to Indicate Requirement Levels. Available online: https://datatracker.ietf.org/doc/html/rfc2119 | +| [RFC8174] | Leiba, B. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. Available online: https://datatracker.ietf.org/doc/html/rfc8174 | +| [SMT] | How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf | +| [IDTA-01002-3-0] | Specification of the Asset Administration Shell Part 2: Application Programming Interfaces. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API.pdf | + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0122-ItemStockExchange/assets/Figure_1.svg b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_1.svg new file mode 100644 index 000000000..6b218d88c --- /dev/null +++ b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_1.svg @@ -0,0 +1,4 @@ + + + +
    Data Provider
    Data Provider
    Connector
    Connector
    Busines Application
    Busines App...
    Catena-X Core Service Provider
    Catena-X Core Service Provider
    IAM
    IAM
    Credential Service
    Credential S...
    Keycloak
    Keycloak
    Data Consumer
    Data Consumer
    Connector
    Connector
    Busines Application
    Busines Applicati...
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
    (8) Get Submodel
    (8) Get Su...
    (5) Query dDTR for Twin and submodel
    (5) Query dDTR for Twin and submodel
    (4) Connector Communication
      (Catalog / Contracting / Transfer)  
    (4) Connector Communication...
    dDTR
    dDTR
    Submodel Endpoint
    Submodel E...
    (10) Get Submodel
    (10) Get S...
    (3) Register Twin
    with Submodels
    (3) Register Twin...
    (2) Register Submodel Endpoint
     at Connector
    (2) Register Submodel Endpoint...
    (9)
    (9)
    Text
    Text
    (6) Get lookup/shells
    by specific asset ids
    (6) Get lookup/shells...
    (1) Register dDTR at Connector
    (1) Register dDTR at Connector
    (7) Get shell-descriptors
    by AAS ID
    (7) Get shell-descriptors...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0122-ItemStockExchange/assets/Figure_2.svg b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_2.svg new file mode 100644 index 000000000..e1ac9bd6d --- /dev/null +++ b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_2.svg @@ -0,0 +1,4 @@ + + + +
    represents same material
    equivalent specific asset IDs, global asset ID,
    different AAS ID
    represents same material...
    PartType for Material (e.g. "Semiconductor")
    PartType for Material...
    Supplier
    Supplier
    Customer
    Custom...
    Asset
    registered in dDTR as AAS
    Asset...
    Submodel
    Submodel
    PartType for Material "Control Unit"
    PartType for Materia...
    ItemStock

    (Direction = Outgoing)
    ItemStock...
    ItemStock

    (Direction = Incoming)
    ItemStock...
    PartTypeInformation
    PartTypeInformation
    SingleLevelUsageAs Planned
    SingleLevelUsageAs P...
    submodel of
    submodel of
    submodel of
    submodel of
    references twin
    references twin
    PartTypeInformation
    PartTypeInformation
    SingleLevel
    BomAsPlanned
    SingleLevel...
    references twin
    references twin
    submodel of
    submodel of
    submodel of
    submodel of
     Legend
     Legend
    Digital Twin in DTR
    Digital Twin in DTR
    Submodel (CX-0122)
    Submodel (CX-0122)
    Submodel (IC Part Type)
    Submodel (IC Part Type)
    submodel of
    submodel of
    references twin
    references twin
    PartType for Material "Semiconductor"
    PartType for Materia...
    submodel of
    submodel of
    submodel of
    submodel of    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0122-ItemStockExchange/assets/Figure_3.puml b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_3.puml new file mode 100644 index 000000000..f46a51236 --- /dev/null +++ b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_3.puml @@ -0,0 +1,43 @@ +@startuml Figure_3 +title Shared Digital Approach - Registration of IC Part Type Twin + +autonumber + +box "Supplier" #LightBlue + participant SupplierApplication as "Application" + participant SupplierDTR as "dDTR" + participant SupplierSubmodelEndpoint as "Submodel Endpoint" + participant SupplierEDC as "Connector" +end box + +box "Customer" #LightGreen + participant CustomerEDC as "Connector" + participant CustomerSubmodelEndpoint as "Submodel Endpoint" + participant CustomerDTR as "dDTR" + participant CustomerApplication as "Application" +end box + +== Supplier registers IC Part Type Twin with Submodel for Customer == + + note over SupplierApplication, SupplierSubmodelEndpoint: Supplier created Part Type Twin + + +== Customer registers IC Part Type Twin with Submodel for Supplier == + CustomerApplication -> CustomerEDC: Register dDTR for partner at Connector + activate CustomerEDC + return OK + + note over CustomerSubmodelEndpoint, CustomerApplication: Keeping Submodel updated only needed\nfor repository pattern + CustomerApplication -> CustomerSubmodelEndpoint: Create Submodel + activate CustomerSubmodelEndpoint + return OK + + CustomerApplication -> CustomerEDC: Register endpoint of Submodel for READ access for partner at Connector + activate CustomerEDC + return OK + + CustomerApplication -> CustomerDTR: Register IC Part Type Twin Shell Descriptor\n with Submodel endpoint\nfor Partner in dDTR\n(DSP endpoint) + activate CustomerDTR + return OK + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0122-ItemStockExchange/assets/Figure_3.svg b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_3.svg new file mode 100644 index 000000000..7372884ad --- /dev/null +++ b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_3.svg @@ -0,0 +1,53 @@ +Shared Digital Approach - Registration of IC Part Type TwinSupplierCustomerApplicationApplicationdDTRdDTRSubmodel EndpointSubmodel EndpointConnectorConnectorConnectorConnectorSubmodel EndpointSubmodel EndpointdDTRdDTRApplicationApplicationSupplier registers IC Part Type Twin with Submodel for CustomerSupplier created Part Type TwinCustomer registers IC Part Type Twin with Submodel for Supplier1Register dDTR for partner at Connector2OKKeeping Submodel updated only neededfor repository pattern3Create Submodel4OK5Register endpoint of Submodel for READ access for partner at Connector6OK7Register IC Part Type Twin Shell Descriptorwith Submodel endpointfor Partner in dDTR(DSP endpoint)8OK \ No newline at end of file diff --git a/docs/standards/CX-0122-ItemStockExchange/assets/Figure_4.puml b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_4.puml new file mode 100644 index 000000000..e42c97417 --- /dev/null +++ b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_4.puml @@ -0,0 +1,84 @@ +@startuml Figure_4 +title Shared Digital Twin Approach - Lookup of IC Part Type Twin + +autonumber + +box "Supplier" #LightBlue + participant SupplierApplication as "Application" + participant SupplierDTR as "dDTR" + participant SupplierSubmodelEndpoint as "Submodel Endpoint" + participant SupplierEDC as "Connector" +end box + +box "Customer" #LightGreen + participant CustomerEDC as "Connector" + participant CustomerSubmodelEndpoint as "Submodel Endpoint" + participant CustomerDTR as "dDTR" + participant CustomerApplication as "Application" +end box + + +== Customer updates Submodel information (repository pattern only) == + note over CustomerSubmodelEndpoint, CustomerApplication: Keeping Submodel updated only needed\nfor repository pattern + CustomerApplication -> CustomerSubmodelEndpoint: Update Submodel information + activate CustomerSubmodelEndpoint + return OK + + +== Supplier reads (updated) Submodel from Customer == + + SupplierApplication -> SupplierEDC: Query Connector Catalog for Customer dDTR access + activate SupplierEDC + + SupplierEDC <-> CustomerEDC: DSP communication + + return Catalog + + SupplierApplication -> SupplierEDC: Negotiate Contract and init transfer + activate SupplierEDC + SupplierEDC <-> CustomerEDC: DSP communication + return OK + + SupplierApplication -> CustomerEDC: Query DTR for IC Part Type Twin based on specific asset ids + activate CustomerEDC + CustomerEDC -> CustomerDTR: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerDTR + CustomerDTR --> CustomerEDC + deactivate CustomerDTR + return ShellDescriptor Ids + + SupplierApplication -> SupplierApplication: select ShellDescriptor ID\nto get ShellDescriptor for\nIC PartType Twin + + SupplierApplication -> CustomerEDC: Lookup IC Part Type Twin based on ShellDescriptor Id + activate CustomerEDC + CustomerEDC -> CustomerDTR: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerDTR + CustomerDTR --> CustomerEDC + deactivate CustomerDTR + return ShellDescriptor + + SupplierApplication -> SupplierApplication: Extract DSP Endpoint and Connector Asset ID for Submodel + + SupplierApplication -> SupplierEDC: Query Connector Catalog for Submodel based on Connector Asset ID + activate SupplierEDC + + SupplierEDC <-> CustomerEDC: DSP communication + + return Catalog + + SupplierApplication -> SupplierEDC: Negotiate Contract for Submodel and init transfer + activate SupplierEDC + SupplierEDC <-> CustomerEDC: DSP communication + return OK + + SupplierApplication -> CustomerEDC: Read Submodel + activate CustomerEDC + CustomerEDC -> CustomerSubmodelEndpoint: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerSubmodelEndpoint + CustomerSubmodelEndpoint --> CustomerEDC + deactivate CustomerSubmodelEndpoint + return Submodel + + SupplierApplication -> SupplierApplication: Use Submodel + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0122-ItemStockExchange/assets/Figure_4.svg b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_4.svg new file mode 100644 index 000000000..fa3889e45 --- /dev/null +++ b/docs/standards/CX-0122-ItemStockExchange/assets/Figure_4.svg @@ -0,0 +1,94 @@ +Shared Digital Twin Approach - Lookup of IC Part Type TwinSupplierCustomerApplicationApplicationdDTRdDTRSubmodel EndpointSubmodel EndpointConnectorConnectorConnectorConnectorSubmodel EndpointSubmodel EndpointdDTRdDTRApplicationApplicationCustomer updates Submodel information (repository pattern only)Keeping Submodel updated only neededfor repository pattern1Update Submodel information2OKSupplier reads (updated) Submodel from Customer3Query Connector Catalog for Customer dDTR access4DSP communication5Catalog6Negotiate Contract and init transfer7DSP communication8OK9Query DTR for IC Part Type Twin based on specific asset ids10forward request based on Connector asset definitions(consumer proxy)11 12ShellDescriptor Ids13select ShellDescriptor IDto get ShellDescriptor forIC PartType Twin14Lookup IC Part Type Twin based on ShellDescriptor Id15forward request based on Connector asset definitions(consumer proxy)16 17ShellDescriptor18Extract DSP Endpoint and Connector Asset ID for Submodel19Query Connector Catalog for Submodel based on Connector Asset ID20DSP communication21Catalog22Negotiate Contract for Submodel and init transfer23DSP communication24OK25Read Submodel26forward request based on Connector asset definitions(consumer proxy)27 28Submodel29Use Submodel \ No newline at end of file diff --git a/docs/standards/CX-0122-ItemStockExchange/assets/Table_12.svg b/docs/standards/CX-0122-ItemStockExchange/assets/Table_12.svg new file mode 100644 index 000000000..a240ddced --- /dev/null +++ b/docs/standards/CX-0122-ItemStockExchange/assets/Table_12.svg @@ -0,0 +1 @@ +Normal ConsumptionCustomer1000100%ProductionOutput Supplier1200100%SituationProdSup100%Prod Sup 100%ProdSup100%ShortageSupprod0%ProdSup100%ProdSup100%CustomerDay 1Day 2Day 3Day 4Day 5-PlanDay 5 -IsDay 6 -PlanDay 6 -IsDay 7 PlanDay 7 IsCall off 1200100012001000120012001000100012001200Delivery1200100012001000120012001000400**12001200Consumption1000100010001000100010001000100010001000Item Stock2002004004006006006000800200SupplierProductionOutput1200120012001200120001200120012001200Item Stock 020020040040040040006000**Shortage situation Delivery quantity remained below planTransferable information from item stock per day \ No newline at end of file diff --git a/docs/standards/CX-0122-ItemStockExchange/assets/Table_14.svg b/docs/standards/CX-0122-ItemStockExchange/assets/Table_14.svg new file mode 100644 index 000000000..3bbb87f71 --- /dev/null +++ b/docs/standards/CX-0122-ItemStockExchange/assets/Table_14.svg @@ -0,0 +1 @@ +Normal Consumption1000100%Quote Supplier A60060%Quote Supplier B40040%SituationShortage Supplier BShortage Supplier BShortage Supplier AShortage Supplier ADay 1Day 2Day 3Day 4Day 5 -PlanDay 5 –IsDay 6 -PlanDay 6 -IsDay 7 PlanDay 7 IsDay 8 PlanDay 8 IsDay 9 PlanDay 9 IsDay 10Day 11Call off customer TOTAL1200100012001000120012001000100012001200100010001200120010001200Allocated call off A7206007206007201100600600720720600600720720600720Allocated call off B480400480400480480400400480480400400480480400480Delivery A7206007206007201100*600600720720600200**720220600720Delivery B480400480400480100**4000**480480400400480780*400480Consumption customer TOTAL1000100010001000100010001000100010001000100010001000100010001000Allocated consumption A6006006006006007406001000600600600520600220600600Allocated consumption B4004004004004002604000400400400480400780400400Item stock customer TOTAL200200400400600600600200600600600040000200Item Stock A120120240240360600600200320320320012000120Item Stock B80801601602400008080800800080*Manual intervention to increase delivery quantity**Shortage situation Delivery quantity remained below planTransferable information from item stock per day \ No newline at end of file diff --git a/docs/standards/CX-0122-ItemStockExchange/assets/Table_16.svg b/docs/standards/CX-0122-ItemStockExchange/assets/Table_16.svg new file mode 100644 index 000000000..dbb713cdc --- /dev/null +++ b/docs/standards/CX-0122-ItemStockExchange/assets/Table_16.svg @@ -0,0 +1 @@ +ConsumptionCustomer A100033%Consumtpion Customer B100033%Production Output Supplier3000100%SituationProdSup100%Prod Sup 100%Prod Sup 100%Shortage Sup prod 0%Shortage Sup prod 0%Prod Sup 100%Day 1Day 2Day 3Day 4Day 5 -PlanDay 5 -IsDay 6 -PlanDay 6 -IsDay 7 PlanDay 7 IsCall off Customer A1000100010001000100010001000100010001000Call of Customer B1000100010001000100010001000100010001000Delivery to Customer A1000100010001000100010001000100010001000Delivery to Customer B1000100010001000100010001000100010001000Item Stock Supplier site TOTAL1000200030004000500020003000010001000Item Stock Supplier site for Customer A5001000150020002500100015000500500Item Stock Supplier site for Customer B5001000150020002500100015000500500Transferable information from item stock per day \ No newline at end of file diff --git a/docs/standards/CX-0123-QualityUseCaseStandard/CX-0123-QualityUseCaseStandard.md b/docs/standards/CX-0123-QualityUseCaseStandard/CX-0123-QualityUseCaseStandard.md new file mode 100644 index 000000000..c34328347 --- /dev/null +++ b/docs/standards/CX-0123-QualityUseCaseStandard/CX-0123-QualityUseCaseStandard.md @@ -0,0 +1,1051 @@ +# CX-0123 Quality Use Case Standard v2.0.0 + +## ABSTRACT + +The Catena-X use case "Quality" provides the ability to detect +quality issues the earliest possible to start root cause analyses and/or to enable +an early warning feature for new quality topics. In subsequent steps, counter +measures can also be defined earlier and monitored. In sum, this reduces the +number of vehicles affected by quality issues and increases the availability of the +vehicle and built-in components. Catena-X use case "Quality" is powered +by Catena-X standard core components to share data from OEM and suppliers +based on data sharing agreements and usage policies. + +## FOR WHOM IS THE STANDARD DESIGNED + +```text + See section Audience & Scope +``` + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +Changes compared to V1.0.0 of CX-0123: + +- Update semantic models QualityTask, PartsAnalyses, ManufacturedPartsQInformation, Fleet.DiagnosticData, Fleet.ClaimData +- Update model Fleet.Vehicles and integrate model Vehicle.ProductDescription +- New semantic models Early Warning Norification and Failure Pattern +- Update 2.1 Data Sharing Rules +- Define Notification Process and API + +## 1 INTRODUCTION + +The Catena-X use case "Quality" uses multiple data models to +exchange data between automotive manufacturer (OEM) and component supplier +(TIER 1) and also along the supply chain betwwen TIER N and TIER N + 1. Each of these data models can be supplied independently. +The QualityTask data model defines the root element for Catena-X-based quality +work. It describes the quality task and why two companies want to work +collaboratively on a quality topic. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +The standard is relevant for the following roles within the scope of the Use Case "Quality" + +- Data Provider/Consumer +- Business Application Provider + +In scope: + +- Data sharing between OEM, TIER 1 and TIER N +- Earliest possible detection of potential issues with products and vehicles in usage +- Understanding of the root cause of the detected issues to enable earliest possible counter measure implementation and monitoring the effectiveness + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +For all participants of the Use Case "Quality" it is necessary to provide and consume the data in accordance to the standardized semantic data models in section [3 Aspect Models](#3-aspect-models) to ensure the defined interoperability requirement "free of choice application" to be able to use the established inhouse tool set for analysis. + +Catena-X use case "Quality" data flow: Data is exported from existing backend systems and mapped to Catena-X aspect models - see list of relevant Catena-X aspect models for use case "Quality" in section [3 Aspect Models](#3-aspect-models) +The so generated files are transferred between different Catena-X participants using a connector conformant to [CX-0018]. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +Since this Use Case Quality Standard describes a set of standards to be fulfilled, participants MUST fulfill all +mentioned standards and the respective conformity assessment criteria in addition to the specific criteria mentioned in +this document. + +The specific criteria described in this document are describing the usage of the central tools as well as common tools +described in the linked standardization documents and therefore compliance **SHOULD BE** checked with the tools provided +for these components. + +### 1.4 EXAMPLES + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +Business Partner Number (BPN) +: A BPN is the unique identifier of a partner within Catena-x + +Connector conformant to [CX-0018] +: The e.g. Tractus-X EDC is a reference implementation of a connector for IDSA conform sovereign data exchange + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normantive* + +### 2.1 "DATA SHARING RULES" + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +To particpate in Data Provisioning for the "Quality Use Case", the following single standards **MUST** be fulfilled by all participants + +- CX - 0018 Data Space Connectivity v3.0.0 + +#### 2.1.2 DATA REQUIRED + +In order to participate in the Catena-X use case "Quality" the following single standards **MUST** be fulfilled by all participants: + +CX - 0018 Data Space Connectivity v3.0.0 + +As OEM data provider for a Supplier as data consumer, if data is provided, I **MUST** provide the data conformant to the following aspect models: + +- Aspect Model QualityTask v2.0.0 +- Aspect Model FleetDiagnosticData v2.0.0 +- Aspect Model FleetClaimData v2.0.0 +- Aspect Model FleetVehicles v2.1.0 +- Aspect Model QualityTaskAttachment v2.0.0 +- Aspect Model FailurePattern v1.0.0 + +As Supplier data provider for an OEM as data consumer, if data is provided, I **MUST** provide the data conformant to the following aspect models: + +- Aspect Model QualityTask v2.0.0 +- Aspect Model PartAnalyses v3.0.0 +- Aspect Model ManufacturedPartsQualityInformation v2.1.0 +- Aspect Model QualityTaskAttachment v2.0.0 +- Aspect Model FailurePattern v1.0.0 + +As Supplier data provider for a Supplier (TIER N) as data consumer, if data is provided, I **MUST** provide the data conformant to the following aspect models: + +- Aspect Model QualityTask v2.0.0 +- Aspect Model PartAnalyses v3.0.0 +- Aspect Model ManufacturedPartsQualityInformation v2.1.0 +- Aspect Model QualityTaskAttachment v2.0.0 + +As OEM data provider or consumer or as Supplier data provider or consumer, if sending an early warning notification I **MUST** be compliant to the early warning notification API. + +- Data provisioning and consuming **MUST** be done according the standardized semantic data models. +- The data provider defines the data content that will be provided. Provided data assets are defined in data sharing agreements and/or data usage policies. + +As Business Application Provider I **MUST** support at least 2 aspect models (minimum standard): One from OEM data provider aspect model list and one from Supplier data provider aspect model list. +As Business Application Provider I **SHOULD** support the early warning notification API. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +```text +Data exchange between the participating partner companies is necessarily to be done for large vehicle and product populations. The data exchange therefore should be done as a file download via EDC according to the following specifications. + +**Asset File type** +It is recommended to create and transfer the files in the type parquet. Exceptions: +- Attachments for the Quality task (Quality Task Attachment) should be created in ZIP format +- Failure Pattern should be transferred in JSON format + +**Asset Transfers via EDC** +File transfer is recommended to be done via EDC S3 plane, The transfer via EDC http data plane is not recommended due to the big data size. +As separator between element names and properties "_" has to be used. + +**S3 Data Address** +These properties are not use-case specific + +| Property | Value | Description | +|-----------------------|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `edc:type` | `"AmazonS3"` | This shows which data source the Data Plane will query. It also determines what other content the `dataAddress` object must hold. | +| `edc:region` | `"eu-west-1"` | This property represents the AWS-region where the source bucket is located. | +| `edc:bucketName` | `"provider-quality-bucket"` | This is the name of the source bucket that the data to-be-transferred resides in. | +| `edc:keyName` | `"path/through/provider/s3"` | This is the path of the file that shall be offered to the dataspace. | +| `edc:accessKeyId` | `""` | Amazon S3 uses this property similarly to how oauth2 client credentials use the `clientId`. Note that this can also be set during deployment-time for the whole S3-dataplane. If it's set here, it will override the default config. | +| `edc:secretAccessKey` | `""` | This secret is used similarly to a `clientSecret` in oauth2 client credentials. + +**Asset Properties** +These properties will be used by the asset consumer to filter dedicated assets from the large number of assete in the catalogue. +| Property | Value | Optional | Description | +|----------------------------------------------------|------------------------------------------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `https://purl.org/dc/terms/type` | `{"@id": "cx-taxo:QualityAsset"}` | | CX-0018 mandates the usage of the dct:type property to signal what kind of Asset a consumer can expect behind a dcat:Dataset. In the Quality Use-Case, this is identified as `https://w3id.org/catenax/taxonomy#QualityAsset`. The expected payload this API serves is determined by the `dcat:conformsTo` property. | +| `https://purl.org/dc/terms/language` | `{"@id": https://w3id.org/idsa/code/EN}` | x | This property is QM-specific. As it points to an IRI, it must be embedded in a json-object with the `@id` key. The use of this is unclear. | +| `https://purl.org/dc/terms/format` | `"application/octet-stream;type=parquet-snappy"` | | This property is QM-specific. dct:format usually points to the correct IANA Media Type. As currently only parquet files are used, the type application/octet-stream with the added property type=parquet-snappy must be used. The syntax is expained [here](https://www.iana.org/assignments/media-types-parameters/media-types-parameters.xhtml). If in the future csv shall be supported, the value could also be `text/csv`. | +| `https://purl.org/dc/terms/description` | `` | x | This property is QM-specific. For human-readable content, rdfs:comment is the usual property but would introduce another namespace so the dct-native property is chosen here. | +| `https://purl.org/dc/terms/conformsTo` | `{"@id":""}` | | This property is QM-specific. It holds the exact aspect-model-URN that defines the schema of the presented dataset including its version. The version in here refers to the data model's version while the EDC-property `cx-common:version` defines the version of the underlying API serving the data. | +| `http://www.w3.org/ns/dcat#qualifiedRelation` | `{"dct:isPartOf": {"@id": ""}}` | | This property is QM-specific. All Asset types defined in this Kit must include this property as it links the data behind an asset with the correct QualityTask. Note that the id of the QualityTask must be used, not the id of the EDC-Asset shielding said QualityTask. | +| `https://w3id.org/edc/v0.0.1/ns/type` | `AmazonS3` | | This property signifies the EDC data plane that the QM data will be transferred over. The expectation that this would be signalled via the dcat:DataSet-dcat:distribution property of the catalog currently isn't implemented in the EDC. Thus the data must be replicated here and is presented via the same property that the consumer-side `transferprocesses` API uses for this same signal. | +| `https://w3id.org/catenax/ontology/common#version` | `"1.0"` | | CX-0018 recommends to use cx-common:version to signal the API's version. Here, the API's version is equivalent to the version of the CX-standard for the Quality domain. Creation is currently in progress as CX-0123 v1.0.0. In this EDC-property, only major and minor increments should be added. | +| `https://purl.org/dc/terms/date)` | `JJJJ-CW-N` | x | This property identifies an update of an already shared catalogue asset. Day is mensioned as calender week day number, e.g. '1' means "monday" | + +**Asset consumption** +The data provided in the asset is build from at least one of 4 to 6 structures. To assure a secure and +smooth exchange flattening rules for the file (csv / xls / Parquet / json) must be applied. This includes checks for format and possible values for each column. If the rules are not applied correctly the mapping of content will not be possible without manual handling effort: + +- Separator +As separator between element names "_" has to be used. + +- Handling of "null values" +Only unique identifier properties (like VAN, serial number, ....) are set to mandatory and all other properties are set to optional. E.g.: If a car has no mileage value after a diagnostic session this property would be left empty. + +- File flattening rules: +To flatten a hierarchical structure into ONE table for data providing the cross-product has to be used: +Beginning from root entity: Do a left outer join with all children one level down. Than for every children that also has child entities: Do a left out join with all child entities one level down. +``` + +Conventions for Use Case Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository. This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas MUST be followed when providing services or apps for data sharing/consuming. + +Additional Details regarding Access Policies + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +Additional Details regarding Usage Policies + +In the context of data usage policies (“Usage Policies”), Participants and related services MUST use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies MAY include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the ODRL policy repository. + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +## 3 ASPECT MODELS + +### 3.1 ASPECT MODEL "QUALITY TASK" + +#### 3.1.1 INTRODUCTION + +The "Quality Task" data model is the root element for Catena-X-based quality work. It is a model that can be created by the automotive manufacturer or by the supplier and describes why data is exchanged over Catena-X network between two companies, who are the responsible people in each company and what should happen with transferred data after the completion of a "Quality Task". + +For data providers: +Each "Quality Task" **MUST** have a unique qualityTaskId conformant to the semantic model. + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under +the terms of the Creative Commons Attribution 4.0 International +(CC-BY-4.0) license, which is available at Creative Commons. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +This semantic model "Qualtiy Task" has the unique identifier + +```text + +```` + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the SAMM command line interface (cli). + +##### 3.1.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. +It can be found in the current version 2.0.0 in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.quality_task/2.0.0/QualityTask.ttl] +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like JSON Schema, aasx for Asset Administration Shell Submodel Template or HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". +It can be found in the current version in the "gen" subfolder in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.quality_task/2.0.0/gen] +``` + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +### 3.2 ASPECT MODEL "FLEET DIAGNOSTIC DATA" + +#### 3.2.1 INTRODUCTION + +The purpose of this section is the description of the "Fleet Diagnostic Data" semantic data model. + +The "Fleet Diagnostic Data" semantic data model is a list diagnostic sessions. +Each diagnostic session contains of a car diagnostic that was performed in a repair shop or over-the-air. + +The target is to provide diagnostic data that can be used for the purpose of early warning or root cause analysis. + +The "Fleet Diagnostic Data" semantic data model is provided by an automotive manufacturer. + +Each "Fleet Diagnostic Data" **MUST** contain an unique sessionId conformant to the semantic model. + +#### 3.2.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.2.3 LICENSE + +This Catena-X data model is made available under +the terms of the Creative Commons Attribution 4.0 International +(CC-BY-4.0) license, which is available at Creative Commons. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.2.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + +``` + +#### 3.2.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the SAMM command line interface (cli). + +##### 3.2.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. +It can be found in the current version 2.0.0 in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.fleet.diagnostic_data/2.0.0/DiagnosticData.ttl] +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like JSON Schema, aasx for Asset Administration Shell Submodel Template or HTML documentation. + +##### 3.2.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". +It can be found in the current version in the "gen" subfolder in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.fleet.diagnostic_data/2.0.0/gen] +``` + +##### 3.2.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +### 3.3 ASPECT MODEL "FLEET CLAIM DATA" + +#### 3.3.1 INTRODUCTION + +The purpose of this section is the description of the "Fleet Claim Data" semantic data model. + +The "Fleet Claim Data" semantic data model is a list of customer complaints(=claim) that are linked to the same or different "Quality Tasks". +One claim: A customer is coming to the repair shop and is indicating a potential malfunction in his car during warranty period. The repair shop tries to fix the problem - by exchanging a potential faulty component by a spare part, by a software update, ... + +The "Fleet Claim Data" semantic data model is provided by an automotive manufacturer. + +Each "Fleet Claim Data" **MUST** contain an unique claimId conformant to the semantic model. + +#### 3.3.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.3.3 LICENSE + +This Catena-X data model is made available under +the terms of the Creative Commons Attribution 4.0 International +(CC-BY-4.0) license, which is available at Creative Commons. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.3.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + +``` + +#### 3.3.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the SAMM command line interface (cli). + +##### 3.3.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. +It can be found in the current version 2.0.0 in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.fleet.claim_data/2.0.0/ClaimData.ttl] +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like JSON Schema, aasx for Asset Administration Shell Submodel Template or HTML documentation. + +##### 3.3.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". +It can be found in the current version in the "gen" subfolder in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.fleet.claim_data/2.0.0/gen] +``` + +##### 3.3.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +### 3.4 ASPECT MODEL "PARTS ANALYSES" + +#### 3.4.1 INTRODUCTION + +The purpose of this section is the description of the "Parts Analyses" semantic data model. + +The "Parts Analyses" semantic data model is a list of analysed parts that were sent back to the component manufacturer (=supplier of the component). +Each part analysis is linked to one or more quality tasks. + +The "Parts Analyses" semantic data model is provided by a component supplier. + +Each dataset in "Parts Analyses" **MUST** contain an unique anonymizedVin conformant to the semantic model. + +#### 3.4.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.4.3 LICENSE + +This Catena-X data model is made available under +the terms of the Creative Commons Attribution 4.0 International +(CC-BY-4.0) license, which is available at Creative Commons. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.4.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + +``` + +#### 3.4.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the SAMM command line interface (cli). + +##### 3.4.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. +It can be found in the current version 3.0.0 in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.parts_analyses/3.0.0/PartsAnalyses.ttl] +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like JSON Schema, aasx for Asset Administration Shell Submodel Template or HTML documentation. + +##### 3.4.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". +It can be found in the current version in the "gen" subfolder in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.parts_analyses/3.0.0/gen] +``` + +##### 3.4.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +### 3.5 ASPECT MODEL "MANUFACTURED PARTS QUALITY INFORMATION" + +#### 3.5.1 INTRODUCTION + +The purpose of this section is the description of the "Manufactured Parts Quality Information" semantic data model. + +The "Manufactured Parts Quality Information" semantic data model is a list of manufactured parts that are involved in one or more quality tasks. + +The "Manufactured Parts Quality Information" semantic data model is provided by a component supplier. + +Each dataset in "Manufactured Parts Quality Information" **MUST** contain at least one part identifier: This can be manufacturerSerialNumber for serial parts or manufacturerPartNumber for non-serial parts. + +#### 3.5.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.5.3 LICENSE + +This Catena-X data model is made available under +the terms of the Creative Commons Attribution 4.0 International +(CC-BY-4.0) license, which is available at Creative Commons. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.5.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + +``` + +#### 3.5.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the SAMM command line interface (cli). + +##### 3.5.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. +It can be found in the current version 2.1.0 in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.manufactured_parts_quality_information/2.1.0/ManufacturedPartsQualityInformation.ttl] +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like JSON Schema, aasx for Asset Administration Shell Submodel Template or HTML documentation. + +##### 3.5.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". +It can be found in the current version in the "gen" subfolder in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.manufactured_parts_quality_information/2.1.0/gen] +``` + +##### 3.5.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +### 3.6 ASPECT MODEL "FLEET VEHICLES" + +#### 3.6.1 INTRODUCTION + +The purpose of this section is the description of the "Fleet Vehicles" semantic data model. + +The "Fleet Vehicles" semantic data model is a list of vehicles that are involved in one or more quality tasks. Each data set is a representation of a vehicle when it was sold to the end-customer: Which equipments was installed in the vehicle, which engine(s) were installed in the vehicle, where was it built and sold. + +The "Fleet Vehicles" semantic data model is provided by an automotive manufacturer. + +Each dataset in "Fleet Vehicles" **MUST** contain an unique anonymizedVin conformant to the semantic model. + +#### 3.6.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.6.3 LICENSE + +This Catena-X data model is made available under +the terms of the Creative Commons Attribution 4.0 International +(CC-BY-4.0) license, which is available at Creative Commons. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.6.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + +``` + +#### 3.6.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the SAMM command line interface (cli). + +##### 3.6.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. +It can be found in the current version 2.1.0 in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.fleet.vehicles/2.1.0/Vehicles.ttl] +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like JSON Schema, aasx for Asset Administration Shell Submodel Template or HTML documentation. + +##### 3.6.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". +It can be found in the current version in the "gen" subfolder in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.fleet.vehicles/2.1.0/gen] +``` + +##### 3.6.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +### 3.7 ASPECT MODEL "QUALITY TASK ATTACHMENT" + +#### 3.7.1 INTRODUCTION + +The QualityTaskAttachment data model describes a way to exchange data and files, which are not available in the existing data models, in the context of a QualityTask. +In order to make the non-standardized data and files machine understandable, they are described using the "Quality Task Attachment" model. + +#### 3.7.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.7.3 LICENSE + +This Catena-X data model is made available under +the terms of the Creative Commons Attribution 4.0 International +(CC-BY-4.0) license, which is available at Creative Commons. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.7.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + +``` + +#### 3.7.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the SAMM command line interface (cli). + +##### 3.7.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. +It can be found in the current version 2.0.0 in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.quality_task_attachment/2.0.0/QualityTaskAttachment.ttl] +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like JSON Schema, aasx for Asset Administration Shell Submodel Template or HTML documentation. + +##### 3.7.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". +It can be found in the current version in the "gen" subfolder in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.quality_task_attachment/2.0.0/gen] +``` + +##### 3.7.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +### 3.8 ASPECT MODEL "EARLY WARNING NOTIFICATION" + +#### 3.8.1 INTRODUCTION + +The data model "Early Warning Notification" describes the payload of a notification used in case of an early warning. An early warning represents an anomaly that is found in the shared data. This notification is used to inform the partner company and initiate further analyses steps. + +#### 3.8.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.8.3 LICENSE + +This Catena-X data model is made available under +the terms of the Creative Commons Attribution 4.0 International +(CC-BY-4.0) license, which is available at Creative Commons. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.8.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + +``` + +#### 3.8.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the SAMM command line interface (cli). + +##### 3.8.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. +It can be found in the current version 1.0.0 in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.early_warning_notification/1.0.0/EarlyWarningNotification.ttl] +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like JSON Schema, aasx for Asset Administration Shell Submodel Template or HTML documentation. + +##### 3.8.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". +It can be found in the current version in the "gen" subfolder in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.early_warning_notification/1.0.0/gen] +``` + +##### 3.8.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +### 3.9 ASPECT MODEL "FAILURE PATTERN" + +#### 3.9.1 INTRODUCTION + +The Failure Pattern data model provides the option to identify one specific hardware or software failure in a vehicle, system or product based on a data signature without analysing the faulty hardware. +The utilisation of a failure pattern is divided into two phases. In a first step, the pattern must be derived. Unique identified root causes from e.g. physical analyses of products serve as a database. +Data in a temporal context, such as failure codes from electronic control units, are analysed using e.g. machine learning algorithms. +Afterwards data patterns are derived that differentiate between the occurrence and non-occurrence of an error. Failure patterns can then be used to check e.g. the effectiveness of quality measures. + +#### 3.9.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.9.3 LICENSE + +This Catena-X data model is made available under +the terms of the Creative Commons Attribution 4.0 International +(CC-BY-4.0) license, which is available at Creative Commons. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.9.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + +``` + +#### 3.9.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the SAMM command line interface (cli). + +##### 3.9.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. +It can be found in the current version 1.0.0 in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.failure_pattern/1.0.0/FailurePattern.ttl] +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like JSON Schema, aasx for Asset Administration Shell Submodel Template or HTML documentation. + +##### 3.9.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". +It can be found in the current version in the "gen" subfolder in the github repository. + +```text +[https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.failure_pattern/1.0.0/gen] +``` + +##### 3.9.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normantive* + +### 4.1 NOTIFICATION API + +Notifications are - in contrast to classical data offers in Catena-X - a way to push data from a sender to a receiver. For now, this notification API is limited to the sending and receiving of early warning notifications as well as the update of the notification status (following a predefined [State Model](#5121-notification-state-model)). + +The API is used as part of the notification process of quality management. It is important to note that this API is designed such that it is based on and extends the QUALITY NOTIFICATION API defined in [CX - 0125 TRACEABILITY USE CASE]. Both may be merged in a future version. + +In this regard it is important to mention, that the API standardized here is not a central API, but an API to be implemented into each participant's quality or traceability solution or solution stack in order to be able to receive information related to early warning and/or quality issues and notifications in the first place. + +So, this chapter describes this early warning notification API with its relevant API endpoints to be created by each supporting quality or traceability solution or solution stack and their integration into the IDSA Protocol and/or the Tractus-X EDC as a reference implementation. On top this chapter describes the Data Asset Structure within the participant who wants to be able to receive notifications and/or updates to notifications. As the notification process includes bi-directional status communication, both entities in a process **MUST** provide these Data Assets and a linkage to corresponding APIs. Furthermore there is also a description of the payload of the notifications for early warning. + +#### 4.1.1 PRECONDITIONS AND DEPENDENCIES + +Application providers **MUST** prove their conformity by providing: + +- An openAPI specification of the endpoints described. +- Examples of the data asset and contract definition structure in their Tractus-X EDC or any other CX-0018 compliant connector. + +The Early Warning Notification API **MUST** be published towards the network using a Data Asset/Contract Definition in terms of the IDSA Protocol as described by the reference implementation [CX - 0018 DATASPACE CONNECTIVITY]. + +The Tractus-X EDC as a reference implementation **SHOULD** BE used and is referenced in this document. Other connectors fulfilling the same standards towards Catena-X **MAY** be leveraged as well. + +It is of importance to mention, that there **MUST** be an API available behind each of the data offers described in the Tractus-X EDC, which works according to the openAPI specifications description. + +Nevertheless, the APIs are **OPTIONAL** to follow the same structure, as there could even be APIs taking over the job of several of the endpoints mentioned. + +The Tractus-X EDC **SHOULD** act as a reverse proxy towards those APIs, as it holds the Data Offers linked to the respective implemented endpoints. + +#### 4.1.2 API SPECIFICATION + +##### 4.1.2.1 API-ENDPOINTS + +The quality notification API **MUST** be implemented as specified in the [openAPI](https://github.com/catenax-eV/product-standardization-prod/blob/main/standards/CX-0123-QuallityUseCaseStandard/2.0.0/src/earlywarningnotification-1-0-0.yaml) documentation. + +In fact, it is **OPTIONAL** to implement the endpoint paths exactly as described in the [openAPI](https://github.com/catenax-eV/product-standardization-prod/blob/main/standards/CX-0123-QuallityUseCaseStandard/2.0.0/src/earlywarningnotification-1-0-0.yaml)). The reason is that those endpoints are not called from any supply chain partner directly. Rather, they are called from the Tractus-X EDC as part of data assets. In that sense, it is just important to implement endpoints that can process the defined request body and respond with the HTTP status codes and - if required - reply with the defined response body. + +The data assets will act similar to a reverse proxy for the notification endpoints, therefore rather the data assets are of significance, which **SHOULD** be exposed towards Catena-X through the Data Offer Catalogues in the Tractus-X EDC or any other CX-0018 compliant connector. + +##### 4.1.2.2 AVAILABLE DATA TYPES + +The quality notification API **MUST** use JSON as the payload transported via HTTP. + +##### 4.1.2.3 API RESOURCES & ENDPOINTS + +The HTTP POST endpoints introduced in this standard **MUST** be called via Data Space Protocol. + +The sending and receiving of notifications **MUST** be built on the basis of HTTP POST endpoints. + +#### 4.1.3 DATA ASSET STRUCTURE + +##### 4.1.3.1 DATA ASSET FOR NOTIFICATION RECEIVE ENDPOINT FOR EARLY WARNING NOTIFICATION RECEIPT + +When using the Tractus-X EDC, the following asset **MUST** be registered. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and provisioning towards Catena-X. + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@type": "Asset", + "@id": "earlywarningnotificationnotification-receive", + "properties": { + "dct:type": { + "@id": "cx-taxo:ReceiveEarlyWarningNotification" + }, + "cx-common:version": "1.2" + }, + "dataAddress": { + ... + } +} +``` + +The variable \{\{httpServerWhichOffersTheHttpEndpoint\}\} **MUST** be set to the HTTP server that offers the endpoint. The path /qualityinvestigations/receive **MAY** align with the HTTP POST path as stated in Section 4.1.2.1. In that sense it can change dependent on the quality or traceability application. + +##### 4.1.3.2 DATA ASSET FOR NOTIFICATION UPDATE ENDPOINT FOR EARLY WARNING NOTIFICATION UPDATE + +When using the Tractus-X EDC the following asset **MUST** be registered. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and provisioning towards Catena-X. + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@type": "Asset", + "@id": "earlywarningnotification-update", + "properties": { + "dct:type": { + "@id": "cx-taxo:UpdateEarlyWarningNotification" + }, + "cx-common:version": "1.2" + }, + "dataAddress": { + ... + } +} +``` + +The variable \{\{httpServerWhichOffersTheHttpEndpoint\}\} **MUST** be set to the HTTP server that offers the endpoint. The path /qualityinvestigations/update **MAY** align with the HTTP POST path as stated in Section 4.1.2.1. In that sense it can change dependent on the quality or traceability application. + +### 4.1.4 VERSIONING + +The API version described in this standard document **MUST** be published in the property https://w3id.org/catenax/ontology/common#version as version 2.0 in dcat:Dataset (http://www.w3.org/ns/dcat#). + +### 4.1.5 EXAMPLES + +Example 1: Early Warning Notification + +```text +I as a partner in an Early Warning project discover a potential quality issue while analysing the common quality data set that was exchanged previously. I want to inform my partner to perform a verfication on his side and want to communicate this data securely and sovereign to him. +``` + +## 5 PROCESSES + +> *This section is normantive* + +### 5.1 NOTIFICATION PROCESS + +This chapter describes the minimum requirements for the notification process and does not go beyond the sending and receiving of early warning notifications. It also illustrates common practices for identifying the correct receiving endpoint when sending a notification. For this purpose, a protocol is described that will be exchanged between quality applications or application +stacks leveraging Tractus-X EDC or any other CX-0018 compliant connector on both ends. + +The notification process therefore takes place between quality or traceability applications or application stacks, and the focus is on minimal interaction, which **MUST** be supported by all applications participating in an early warning notification scenario. + +Application internals like user journeys, process steps or workflows in an application are not standardized within Catena-X, and therefore omitted. + +Note that the process described here is same as the one described for Quality Notification defined in [CX - 0125 TRACEABILITY USE CASE] + +#### 5.1.1 ACTORS AND ROLES + +Catena-X does not standardize user-roles at the moment. The actors are quality applications of the companies in a supply chain. + +#### 5.1.2 PROCESS REPRESENTATION + +The exchange of notifications follows the IDSA protocol. + +On top, a notification state model has been described. + +##### 5.1.2.1 NOTIFICATION STATE MODEL + +The notification itself has various states. The states and their cycle are described in the following figure: + +![CX0125_Notification-State-Model.png](./assets/CX0125_Notification-State-Model.png) + +***Figure 1: Description of Process*** + +The state of a notification MUST be exchanged via the [4.1. EARLY WARNING Notification API](#41-notification-api). + +##### 5.1.2.2 PROCESSES FOR SENDING AND UPDATING EARLY WARNING NOTIFICATIONS + +Below the sequence for sending and updating of notifications +between (quality or traceability) applications is shown in UML sequence diagrams +In all cases, HTTP POST requests **MUST** be used. The corresponding HTTP +endpoints are described in chapter [4.1 EARLY WARNING Notification API](#41-notification-api). + +To read the UML sequence diagrams correctly, some remarks below: + +- The shown Notification Tractus-X EDC Adapter is **OPTIONAL**. It is just one + option to send a notification via the Tractus-X EDC control and data plane. It + is important, that a similar functionality **MUST** be + provided/implemented by the (quality or traceability) application vendor. The + Notification Tractus-X EDC Adapter or a similar component / functionality will + not be provided as a central service from Catena-X. + +- To discover where a notification **MUST** be sent to, the (quality or traceability) + application **MUST** resolve the BPN of the receiver. This can either + happen through the (quality or traceability) application holding this + information in its data model, or it could - alternatively - also be + resolved e.g. via a lookup of the digital twin in the central asset + administration shell (AAS) registry or by using services from the + BPDM use case. + +- The resolution of the Tractus-X EDC URL for a given BPN **SHOULD BE** done via the + EDC Discovery Service API \[CX-0001\]. The entry for each Tractus-X EDC into + this Discovery Service is done via the Catena-X Portal. + +- In each UML sequence diagram the step \[01\] describes the + publishing of the notification endpoints as described in the above + sections. + +###### 5.1.2.2.1 SENDING AND RECEIVING OF AN EARLY WARNING NOTIFICATION OR A QUALITY INVESTIGATION + +Below, the UML sequence diagram to send and receive an early warning notification is depicted. This is the same as sending and receiving a quality notification. + +In addition to the above-mentioned general remarks, the following remark +has to be mentioned: + +- The status transition from SENT to RECEIVED **MUST** be done by the + +> sender once it received the Http status code 201 from the receiver. This status is not communicated from the sender to the receiver. + +![CX0125_SendAndReceive_2.png](./assets/CX0125_SendAndReceive_2.png) + +***Figure 2: Send and Receive Early Warning or Quality Notification*** + +###### 5.1.2.2.2 UPDATE OF AN EARLY WARNING NOTIFICATION OR A QUALITY INVESTIGATION + +Below, the UML sequence diagram to update an early warning notification is +depicted. This is the same as updating a quality notification. + +![CX0125_UpdateQuality_4.png](./assets/CX0125_UpdateQuality_4.png) + +***Figure 3: Update Early Warning or Quality Investigation*** + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normantive* + +- CX - 0001 EDC Discovery API v1.0.2 +- CX - 0003 SAMM Aspect Meta Model v1.1.0 +- CX - 0018 Data Space Connectivity v3.0.0 +- CX - 0125 Traceability Use Case v2.0.0 + +### 6.2 NON-NORMATIVE REFERENCES + +### 6.3 REFERENCE IMPLEMENTATIONS + +## ANNEXES + +### FIGURES + +### TABLES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0123-QualityUseCaseStandard/assets/CX0125_Notification-State-Model.png b/docs/standards/CX-0123-QualityUseCaseStandard/assets/CX0125_Notification-State-Model.png new file mode 100644 index 000000000..0e0cf5672 Binary files /dev/null and b/docs/standards/CX-0123-QualityUseCaseStandard/assets/CX0125_Notification-State-Model.png differ diff --git a/docs/standards/CX-0123-QualityUseCaseStandard/assets/CX0125_SendAndReceive_2.png b/docs/standards/CX-0123-QualityUseCaseStandard/assets/CX0125_SendAndReceive_2.png new file mode 100644 index 000000000..0b20c9724 Binary files /dev/null and b/docs/standards/CX-0123-QualityUseCaseStandard/assets/CX0125_SendAndReceive_2.png differ diff --git a/docs/standards/CX-0123-QualityUseCaseStandard/assets/CX0125_UpdateQuality_4.png b/docs/standards/CX-0123-QualityUseCaseStandard/assets/CX0125_UpdateQuality_4.png new file mode 100644 index 000000000..5b9b6a3a5 Binary files /dev/null and b/docs/standards/CX-0123-QualityUseCaseStandard/assets/CX0125_UpdateQuality_4.png differ diff --git a/docs/standards/CX-0125-TraceabilityUseCase/CX-0125-TraceabilityUseCase.md b/docs/standards/CX-0125-TraceabilityUseCase/CX-0125-TraceabilityUseCase.md new file mode 100644 index 000000000..f1d87b599 --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/CX-0125-TraceabilityUseCase.md @@ -0,0 +1,703 @@ +# CX-0125 Traceability Use Case v2.0.0 + +## ABSTRACT + +This standard is used to define the basic rules to participate in the Traceability Use Case. + +The use case is based on the industry core and uses the digital twins and aspect models of the industry core. Furthermore it includes +use case-specific aspect models (e.g. TractionBatteryCode) that go beyond the industry core and are used to make various entities in the network, such as parts, traceable. + +In addition, this document contains necessary standards for applications to send standardized notifications to exchange Quality Alerts and Quality Investigations in Catena-X. Quality Investigations refer to sending standardised notifications to suppliers (top-down) while Quality Alerts refer to sending notifications to customers (bottom-up). Those notifications will enable the industry to exchange and act upon quality issues in a more standardised, integrated, accelerated and precise manner. This document describes the minimal requirements of the notification process a traceability application or application stack needs to fulfill for being interoperable within the Catena-X platform as well as the specific API endpoints and their integration into IDSA conform data assets. + +## FOR WHOM IS THE STANDARD DESIGNED   + +This standard is designed for everybody who wants to participate in the traceability use case. + +The following features are provided: + +- Traceability of products (e.g. vehicles), parts and material (physical assets) +- Notification of quality issues within the value chain + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +- Redundancies to the standard CX-0127 in all relevant chapters removed: Submodel SerialPart, Submodel Batch, Submodel SingleLevelBoMAsBuilt +- Adapted parts (introductions, examples) of the standard document contents to suit the use case specifications +- Quality Alerts are set to mandatory +- New paragraph "Conventions for Use Case Policy in context data exchange" in [Section 2.1.3](#213-additional-requirements) +- Added notes for versioning in [Section 2.1.3](#213-additional-requirements) +- Deleted "Every certified business application relying on aspects models of this standard **MUST** be able to consume data conformant to the semantic models specified in this document." from [Section 3](#3-aspect-models) +- Deleted old references in [Section 6.1](#61-normative-references) + +Note: This release (**24.05.**) contains **breaking changes**! + +## 1 INTRODUCTION + +This document summarizes all standards to be supported by a network participants IT infrastructure to participate for the **Use Case Traceability**. This involves protocols, semantic models and platform capabilities to be used. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This document is targeting subsets of the following roles: + +- Data Provider (only for notifications) / Consumer +- Business Application Provider +- Enablement Service Provider + +Furthermore, this standard applies to Traceability Applications or Application stacks and participants that + +- want to provide (only for notifications) and/or consume data +- want to exchange quality notifications and quality investigations data leveraging Traceability solutions (not to be a general solution pattern for notifications across various use cases (api, process), only for sending and receiving of quality notifications in a traceability context) + +Note: Fulfilling a use-case standard by a data provider / consumer can be done in two ways: + +1. Purchase a certified app for the use-case. In this case the data provider / consumer does not need to prove conformity again and +2. Data Provisioning / Consumption without a certified app for the use-case. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +Traceability of parts and materials is crucial in the automotive industry to enable e.g. quality management and circular economy. So, the aim of the Use Case Traceability is to trace physical parts and materials across the entire value creation chain to enable data driven use cases over all n-tier levels without compromising data sovereignty. + +In order to create this transparency on physical assets, relevant data must be made available by all participants of a value chain. This process is described in the standard **CX - 0127 INDUSTRY CORE: PART INSTANCE 2.0.0.** This standard enables data and app providers to deliver solutions for building data chains for serialized parts or batches. This is achieved via the standardized creation of digital twins of vehicles, parts and materials as well as the logical linking to their sub-components (Bill of Material, BoM). The default visibility of digital twins and their respective semantic models follows the one-up/one-down principle. + +By tracking and tracing back the sourcing of serialized parts or batches, manufactures can quickly identify the source of any quality issue and take corrective actions to address them. Comprehensive traceability across the value creation network enables the automotive and further industries to quickly respond to any quality issues in their supply chain. Standardized Quality Alerts and Quality Investigations based on Part Instance digital twins may be used for this purpose within the Catena-X network. + +The following figure provides an overview of the architecture of all components involved in relation to quality notifications. + +![CX0125_notification_architecture_level_1.svg](./assets/CX0125_notification_architecture_level_1.svg) + +***Figure 1: Architecture Overview*** + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +Sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +All participants* and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). Please refer to: https://catena-x.net/en/catena-x-introduce-implement/certification for the process of conformity assessment and certification. + +Since this document describes a set of standards to be fulfilled, participants **MUST** fulfill all mentioned standards and the respective conformity assessment criteria in addition to the specific criteria mentioned in this document. + +The specific criteria defined in this document are describing the usage of the central tools as well as common tools described in the linked standardization documents and therefore compliance **SHOULD BE** checked with the tools provided for these components. + +The proof of conformity for a single semantic model is done according to the general rules for proving the conformity of data provided to a semantic model or the ability to consume the corresponding data. + +In terms of conformity the openAPI specification of the application or endpoints being exposed via the Tractus-X EDC or any other CX-0018 compliant connector **MUST** be checked against the standardized openAPI specification. + +Examples of data assets and contract offer structure in the Tractus-X EDC or any other CX-0018 compliant connector **MUST** correspond to the described structure. + +The versions of the standardization documents valid for this standard are mentioned in sections where the [standalone standards](#211-list-of-standalone-standards), [normative references](#61-normative-references) and [non-normative references](#62-non-normative-references) are listed. The valid versions are not specifically mentioned in the body text. + +**Disclaimer: The operating model released by the Catena-X association will define the roadmap, content and scope for the certification process. This will include the roles, certification and further assessment procedures as well as the rollout phases.* + +### 1.4 EXAMPLES + +Examples for data models: See according subsection [3 Aspect Models](#3-aspect-models). + +Examples for APIs: See according subsection [4 APPLICATION PROGRAMMING INTERFACES](#4-application-programming-interfaces) + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +**Application Programming Interface (API):** +An API is a way for two or more computer programs to communicate with each other. + +**Aspect Model:** +A formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an aspect. + +Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model. + +Note 2 to entry: Aspect Models are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +*[Source: Catena-X, CX-0002, note 3 removed]* + +**Asset:** +An Asset describes on Data Provider side the data set which will be shared or can be consumed by a Data Consumer. + +**Asset Administration Shell (AAS):** +The AAS is a digital representation of an asset. It is a form of a digital twin. + +**Bill of Material (BoM):** +A bill of material resembles the structure of a product. It is a list of all raw materials, sub-assemblies and sub-components that are needed to manufacture the end procuct. At Catena-X Traceability we consider more than one single BoM. The BoM changes during the lifecyle and therefore, we are talking about different BoMs in different lifecycles. + +**Business Partner Number (BPN):** +A BPN is the unique identifier of a partner within Catena-X. + +**Tractus-X Eclipse Dataspace Connector (Tractus-X EDC)**: +The Tractus-X EDC is a reference implementation for a connector conformant to CX-0018 currently acting as a de-facto standard and/or reference Implementation within Catena-X. When mentioning the Tractus-X EDC in this standard, any other CX-0018 conformant connector is also a valid option. + +**HTTP:** +Hypertext Transfer Protocol (HTTP) is an application-layer protocol for transmitting hypermedia documents, such as HTML. It was designed for communication between web browsers and web servers, but it can also be used for other purposes. + +**International Data Space Association (IDSA):** +The IDSA is on a mission to create the future of the global, digital economy with International Data Spaces (IDS), a secure, sovereign system of data sharing in which all participants can realize the full value of their data. + +**International Data Space (IDS):** +The International Data Space enables new "smart services" and innovative business processes to work across companies and industries while ensuring that the self-determined control of data use (data sovereignty) remains in the hands of data providers. + +**IDSA Protocol:** +The IDSA Protocol being used for data exchange in an International Dataspace. This includes contract negotiation. + +**Part Instance:** +A part instance is a physically produced instance (e.g. serialized part, batch, just-in-sequence-part) of a part type. + +**Serialized part:** +Instance of a part, where the particular instance can be uniquely identified by means of a serial number, a similar identifier (e.g. VAN) or a combination of multiple identifiers (e.g. combination of manufacturer, date and number). + +**Subcomponent:** +A Subcomponent is a separate product that can be assembled into a customer product. + +**UML:** +The unified modeling language (UML) is a general-purpose visual modeling language that is intended to provide a standard way to visualize the design of a system. UML provides a standard notation for many types of diagrams which can be roughly divided into three main groups: behavior diagrams, interaction diagrams, and structure diagrams. + +**Vehicle Anonymised Number (VAN):** +A number mapped 1:1 to VIN, but pseudonomised. + +**Vehicle Identification Number (VIN):** +The VIN number is a 17-character code assigned by the manufacturer to every vehicle, providing specific information about its make, model, year of manufacture, and other key features. It is a unique identifier that allows the vehicle to be easily tracked and identified throughout its lifespan.  Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 "QUALITY NOTIFICATIONS AND DATA EXCHANGE" + +This chapter describes and collects necessary standards for applications that enable the standardized exchange of Quality Alert and Quality Investigation in Catena-X. Quality refer to sending standardised notifications to suppliers (top-down) while Quality Alerts refer to sending notifications to customers (bottom-up). Those notifications will enable the industry to exchange and act upon quality issues in a more standardised, integrated, accelerated and precise manner. + +It is tightly bound to the Industry Core, as Quality Alerts and Quality Investigation Requests should reference batches and/or serialized part instances as described in the standard **CX - 0127 INDUSTRY CORE: PART INSTANCE**. + +The standards for Traceability and Industry Core: Part Instance serve as an enabler for the standardized exchange of Quality Alert and Quality Investigations by introducing network-wide unique identifiers for serialized parts or batches. Its linked standards are to be used in order to be interoperable. + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +> *This section is normative* + +To participate in Notifications, the following single standards **MUST** be fulfilled by all participants for which the standard is relevant: + +- CX-0001 EDC DISCOVERY API 1.0.2 +- CX-0002 DIGITAL TWINS IN CATENA-X 2.2.0 +- CX-0018 DATASPACE CONNECTIVITY 3.0.0 +- CX-0127 INDUSTRY CORE: PART INSTANCE 2.0.0 + +#### 2.1.2 DATA REQUIRED + +A digital twin **MAY** be created for serialized part or batch of materials produced by the manufacturer. +The digital twin **MUST** be provisioned via an Asset Administration Shell as per CX-0002 and registered in a decentral Digital Twin Registry of the data provider (or the decentral Digital Twin Registry host of the manufacturer) as described in CX-0002. + +The IDS protocol as described in CX-0018 **MUST** be followed in the data exchange. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +As the IDS protocol is being used, data **MUST NOT** be transferred before a corresponding contract negotiation has been successfully passed by the participants of the data exchange and a valid contract is present as described in CX-0018. + +The described [Notification Process](#51-notification-process) and especially status schema **MUST** be supported. + +The described [Notification API](#41-quality-notification-api) **MUST** be provisioned in order to receive Quality Alerts or Quality Investigation. +The required data offers for Quality Alerts and Quality Investigations **MUST** be created and linked to the described endpoints of the [Notification API](#41-quality-notification-api). + +#### Conventions for Use Case Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +##### Additional Details regarding Access Policies + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +##### Additional Details regarding Usage Policies + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +##### Versioning + +The Aspect Models that are deployed as Digital Twins **MUST** be published in dcat:Dataset (http://www.w3.org/ns/dcat#) in the property that holds the full URN of the Aspect Model https://admin-shell.io/aas/3/0/HasSemantics/semanticId. Versions are explicitly contained in the URN. +The API versions **MUST** be published in the property https://w3id.org/catenax/ontology/common#version as version X.Y in dcat:Dataset (http://www.w3.org/ns/dcat#). +Note: Data Assets differentiated only by major version **MUST** be offered in parallel. The current standard and API versions mark the start of Life Cycle Management in Catena-X operations. Previous versions are dismissed. + +## 3 ASPECT MODELS + +> *This section is normative* + +An overview of the relevant aspect models of this standard. + +- TractionBatteryCode + +If a data provider decides to provide data on aspect models of this standard they **MUST** provide the data conformant to the semantic models specified in this document. + +Data consumers and data provider **MUST** comply with the license of the semantic models. + +The submodel data **MUST** be transferred using the IDS Protocol as described in CX-0018. +The Tractus-X EDC as a reference implementation is **RECOMMENDED** to be used as a connector conformant to CX-0018. + +Data providers **MUST** provide data as part of a digital twin of the asset for serialized parts conformant to CX–0002. The JSON Payloads of data providers **MUST** be conformant to the JSON Schemas as specified in this document. + +The unique identifier of the semantic model specified in this document **MUST** be used by the data provider to define the semantics of the data being transferred. + +### 3.1 ASPECT MODEL "TractionBatteryCode" + +#### 3.1.1 INTRODUCTION   + +This semantic model describes a submodel for a digital twin of a traction battery or a respective subcomponent (pack, module or cell). This aspect model provides information about the traction battery code of a battery component. A traction battery code is an identification code according to GB/T 34014-2017 which has to be provided when exporting automotive traction batteries to the People's Republic of China. In addition to the traction battery code, the model also contains classification of the corresponding battery component and all subcomponents. + +On the lowest level, the cell level, the model contains only the traction battery code for the cell and the information on the classification which describes if the corresponding part is a cell, a module or a pack. On the middle level, the module level, the model contains the same information for the module (code and classification). In addition to that, however, it also includes a list of the cells information that are assembled into the module. Analogue to this, on pack level, the model contains the information of the pack itself as well as the information of the modules assembled into the pack and the cells assembled into the modules. + +By accessing this aspect you can get all traction battery codes that are a part of the corresponding part of the traction battery. + +Note: The presented aspect model is in version 2.0.0 and **optional**. + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#62-non-normative-references). + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003. + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +**urn:samm:io.catenax.traction_battery_code:2.0.0#TractionBatteryCode** + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + +TractionBatteryCode **v2.0.0** (optional) + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.traction_battery_code/2.0.0/TractionBatteryCode.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like for example a JSON Schema, AASX for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)]. + +#### 3.1.6 EXAMPLES + +Example JSON Payload: Submodel "TractionBatteryCode" for a Battery Cell. + +```json +{ + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382320" +} +``` + +Example JSON Payload: Submodel "TractionBatteryCode" for a Battery Module + +```json +{ + "productType": "module", + "tractionBatteryCode": "B54MCPM27KLPCLE6A7519857", + "subcomponents": [ + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382320" + }, + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382321" + } + ] +} +``` + +Example JSON Payload: Submodel "TractionBatteryCode" For a Battery Pack + +```json +{ + "productType": "pack", + "tractionBatteryCode": "4A6PCPM27KLPCLE742946319", + "subcomponents": [ + { + "productType": "module", + "tractionBatteryCode": "B54MCPM27KLPCLE6A7519857", + "subcomponents": [ + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382320" + }, + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382321" + } + ] + }, + { + "productType": "module", + "tractionBatteryCode": "B54MCPM27KLPCLE6A7519858", + "subcomponents": [ + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382322" + }, + { + "productType": "cell", + "tractionBatteryCode": "X12CCPM27KLPCLE662382323" + } + ] + } + ] +} +``` + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +### 4.1 QUALITY NOTIFICATION API   + +Notifications are - in contrast to classical data offers in Catena-X - a way to push data from a sender to a receiver. For now, this notification API is limited to the sending and receiving of quality notifications as well as the update of the notification status (following a predefined [State Model](#5121-notification-state-model)). The API is used as part of the notification process of traceability. + +In this regard it is important to mention, that the API standardized here is not a central API, but an API to be implemented into each participant's traceability solution or solution stack in order to be able to receive information related to quality issues and notifications in the first place. + +So, this chapter describes this quality notification API with its relevant API endpoints to be created by each traceability solution or solution stack and their integration into the IDSA Protocol and/or the Tractus-X EDC as a reference implementation. On top this chapter describes the Data Asset Structure within the participant who wants to be able to receive notifications and/or updates to notifications. As the notification process includes bi-directional status communication, both entities in a process **MUST** provide these Data Assets and a linkage to corresponding APIs. Furthermore there is also a description of the payload of the notifications for quality investigations and quality alerts. + +#### 4.1.1 PRECONDITIONS AND DEPENDENCIES + +Application providers **MUST** prove their conformity by providing: + +- An openAPI specification of the endpoints described. + +- Examples of the data asset and contract definition structure in their Tractus-X EDC or any other CX-0018 compliant connector. + +The Quality Notification API **MUST** be published towards the network using a Data Asset/Contract Definition in terms of the IDSA Protocol as described by the reference implementation [CX - 0018 DATASPACE CONNECTIVITY]. + +The Tractus-X EDC as a reference implementation **SHOULD** BE used and is referenced in this document. Other connectors fulfilling the same standards towards Catena-X **MAY** be leveraged as well. + +It is of importance to mention, that there **MUST** be an API available behind each of the data offers described in the Tractus-X EDC, which works according to the openAPI specifications description. + +Nevertheless, the APIs are **OPTIONAL** to follow the same structure, as there could even be APIs taking over the job of several of the endpoints mentioned. + +The Tractus-X EDC **SHOULD** act as a reverse proxy towards those APIs, as it holds the Data Offers linked to the respective implemented endpoints. + +#### 4.1.2 API SPECIFICATION + +##### 4.1.2.1 API-ENDPOINTS + +The quality notification API **MUST** be implemented as specified in the [openAPI](./assets/notifications-1-2-1.yaml) documentation. + +In fact, it is **OPTIONAL** to implement the endpoint paths exactly as described in the [openAPI](./assets/notifications-1-2-1.yaml). The reason is that those endpoints are not called from any supply chain partner directly. Rather, they are called from the Tractus-X EDC as part of data assets. In that sense, it is just important to implement endpoints that can process the defined request body and respond with the HTTP status codes and - if required - reply with the defined response body. + +The data assets will act similar to a reverse proxy for the notification endpoints, therefore rather the data assets are of significance, which **SHOULD** be exposed towards Catena-X through the Data Offer Catalogues in the Tractus-X EDC or any other CX-0018 compliant connector. + +##### 4.1.2.2 AVAILABLE DATA TYPES + +The quality notification API **MUST** use JSON as the payload transported via HTTP. + +##### 4.1.2.3 API RESOURCES & ENDPOINTS + +The HTTP POST endpoints introduced in this standard **MUST** be called via Data Space Protocol. + +The sending and receiving of notifications **MUST** be built on the basis of HTTP POST endpoints. + +#### 4.1.3 DATA ASSET STRUCTURE + +##### 4.1.3.1 DATA ASSET FOR NOTIFICATION RECEIVE ENDPOINT FOR QUALITY INVESTIGATION RECEIPT + +When using the Tractus-X EDC, the following asset **MUST** be registered. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and provisioning towards Catena-X. + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@type": "Asset", + "@id": "qualityinvestigationnotification-receive", + "properties": { + "dct:type": { + "@id": "cx-taxo:ReceiveQualityInvestigationNotification" + }, + "cx-common:version": "1.2" + }, + "dataAddress": { + ... + } +}   +``` + +The variable \{\{httpServerWhichOffersTheHttpEndpoint\}\} **MUST** be set to the HTTP server that offers the endpoint. The path /qualityinvestigations/receive **MAY** align with the HTTP POST path as stated in Section 4.1.2.1. In that sense it can change dependent on the traceability application. + +##### 4.1.3.2 DATA ASSET FOR NOTIFICATION RECEIVE ENDPOINT FOR QUALITY ALERT RECEIPT + +When using the Tractus-X EDC, the following asset **MUST** be registered. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and provisioning towards Catena-X. + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@type": "Asset", + "@id": "qualityalertnotification-receipt", + "properties": { + "dct:type": { + "@id": "cx-taxo:ReceiveQualityAlertNotification" + }, + "cx-common:version": "1.2" + }, + "dataAddress": { + ... + } +} +``` + +The variable \{\{httpServerWhichOffersTheHttpEndpoint\}\} **MUST** be set to the HTTP server that offers the endpoint. The path /qualityalerts/receive **MAY** align with the HTTP POST path as stated in Section 4.1.2.1. In that sense it can change dependent on the traceability application. + +##### 4.1.3.3 DATA ASSET FOR NOTIFICATION UPDATE ENDPOINT FOR QUALITY INVESTIGATION UPDATE + +When using the Tractus-X EDC the following asset **MUST** be registered. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and provisioning towards Catena-X. + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@type": "Asset", + "@id": "qualityinvestigationnotification-update", + "properties": { + "dct:type": { + "@id": "cx-taxo:UpdateQualityInvestigationNotification" + }, + "cx-common:version": "1.2" + }, + "dataAddress": { + ... + } +}   + +``` + +The variable \{\{httpServerWhichOffersTheHttpEndpoint\}\} **MUST** be set to the HTTP server that offers the endpoint. The path /qualityinvestigations/update **MAY** align with the HTTP POST path as stated in Section 4.1.2.1. In that sense it can change dependent on the traceability application. + +##### 4.1.3.4 DATA ASSET FOR NOTIFICATION UPDATE ENDPOINT FOR QUALITY ALERT UPDATE + +When using the Tractus-X EDC the following asset **MUST** be registered. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and provisioning towards Catena-X. + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@type": "Asset", + "@id": "qualityalertnotification-update", + "properties": { + "dct:type": { + "@id": "cx-taxo:UpdateQualityAlertNotification" + }, + "cx-common:version": "1.2" + }, + "dataAddress": { + ... + } +} + +``` + +The variable \{\{httpServerWhichOffersTheHttpEndpoint\}\s} **MUST** be set to the HTTP server that offers the endpoint. The path /qualityalerts/update **MAY** align with the HTTP POST path as stated in Section 4.1.2.1. In that sense it can change dependent on the traceability application. + +### 4.1.4 VERSIONING + +The API version described in this standard document **MUST** be published in the property https://w3id.org/catenax/ontology/common#version as version 2.0 in dcat:Dataset (http://www.w3.org/ns/dcat#). + +### 4.1.5 EXAMPLES + +Example 1: Quality Investigation + +```text +I as a customer discover a quality issue during assembly with several parts of a specific supplier. I want to inform my supplier to perform a quality investigation on his side and want to communicate this data securely and sovereign to him. +``` + +Example 2: Quality Alert + +```text +I as a supplier discover a problem with specific batches or serialized parts on my end affecting also parts already shipped. I want to communicate this data securely and sovereign to my customers.   +``` + +## 5 PROCESSES + +> *This section is normative* + +### 5.1 QUALITY NOTIFICATION PROCESS + +This chapter describes the minimum requirements for the notification process and does not go beyond the sending and receiving of quality notifications. It also illustrates common practices for identifying the correct receiving endpoint when sending a notification. For this purpose, a protocol is described that will be exchanged between traceability applications or application stacks leveraging Tractus-X EDC or any other CX-0018 compliant connector on both ends. + +The notification process therefore takes place between traceability applications or application stacks, and the focus is on minimal interaction, which **MUST** be supported by all applications participating in a quality notification or quality investigation scenario. + +Application internals like user journeys, process steps or workflows in an application are not standardized within Catena-X, and therefore omitted. + +#### 5.1.1 ACTORS AND ROLES + +Catena-X does not standardize user-roles at the moment. The actors are traceability applications of the companies in a supply chain. + +#### 5.1.2 PROCESS REPRESENTATION + +The exchange of notifications follows the IDSA protocol. + +On top, a notification state model has been described. + +##### 5.1.2.1 NOTIFICATION STATE MODEL + +The notification itself has various states. The states and their cycle are described in the following figure: + +![CX0125_Notification-State-Model.svg](./assets/CX0125_Notification-State-Model.svg) + +***Figure 2: Description of Process*** + +The state of a notification MUST be exchanged via the [Notification API](#41-quality-notification-api). + +##### 5.1.2.2 PROCESSES FOR SENDING AND UPDATING NOTIFICATIONS + +Below the sequence for sending and updating of notifications between (traceability) applications is shown in UML sequence diagrams In all cases, HTTP POST requests **MUST** be used. The corresponding HTTP endpoints are described in chapter [Notification API](#41-quality-notification-api). + +To read the UML sequence diagrams correctly, some remarks below: + +- The shown Notification Tractus-X EDC Adapter is not mandatory. It is just one option to send a notification via the Tractus-X EDC control and data plane. It is important, that a similar functionality must be provided/implemented by the (traceability) application vendor. The Notification Tractus-X EDC Adapter or a similar component / functionality will not be provided as a central service from Catena-X. + +- To discover where a notification **MUST** be sent to, the (traceability) + application **MUST** resolve the BPN of the receiver. This can either + happen through the (traceability) application holding this + information in its data model, or it could - alternatively - also be + resolved e.g. via a lookup of the digital twin in the central asset + administration shell (AAS) registry or by using services from the + BPDM use case. + +- The resolution of the Tractus-X EDC URL for a given BPN SHOULD be done via the + EDC Discovery Service API \[CX-0001\]. The entry for each Tractus-X EDC into + this Discovery Service is done via the Catena-X Portal. + +- In each UML sequence diagram the step \[01\] describes the + publishing of the notification endpoints as described in the above + sections. + +###### 5.1.2.2.1 SENDING AND RECEIVING OF A QUALITY INVESTIGATION + +Below, the UML sequence diagram to send and receive a quality +investigation is depicted. + +In addition to the above-mentioned general remarks, the following remark +has to be mentioned: + +- The status transition from SENT to RECEIVED **MUST** be done by the + +> sender once it has received the HTTP status code 201 from the receiver. This status is not communicated from the sender to the receiver. + +![CX0125_SendAndReceive_2.svg](./assets/CX0125_SendAndReceive_2.svg) + +***Figure 3: Send and Receive Quality Investigation*** + +###### 5.1.2.2.2 SENDING AND RECEIVING OF A QUALITY ALERT + +Below, the UML sequence diagram to send and receive a quality alert is +depicted. + +In addition to the above-mentioned general remarks, the following remark +has to be mentioned: + +- The status transition from SENT to RECEIVED **MUST** be done by the + +> sender once it has received the HTTP status code 201 from the receiver. This status is not communicated from the sender to the receiver. + +![CX0125_SendAndReceive_3.svg](./assets/CX0125_SendAndReceive_3.svg) + +***Figure 4: Send and Receive Quality Alert*** + +###### 5.1.2.2.3 UPDATE OF A QUALITY INVESTIGATION + +Below, the UML sequence diagram to update a quality investigation is +depicted. + +![CX0125_UpdateQuality_4.svg](./assets/CX0125_UpdateQuality_4.svg) + +***Figure 5: Update Quality Investigation*** + +###### 5.1.2.2.4 UPDATE OF A QUALITY ALERT + +Below, the UML sequence diagram to update a quality alert is depicted. + +![CX0125_UpdateQualityAlert_5.svg](./assets/CX0125_UpdateQualityAlert_5.svg) + +***Figure 6: Update Quality Alert*** + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normative* + +- CX-0001 EDC Discovery API 1.0.2 +- CX-0002 Digital Twins in Catena–X 2.2.0 +- CX-0003 SAMM Aspect Meta Model 1.1.0 +- CX-0018 Dataspace Connectivity 3.0.0 +- CX-0127 Industry Core - Part Instance 2.0.0 +- Tractus-X EDC Reference Implementation - https://github.com/eclipse-tractusx/tractusx-edc + +[^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf +[^2]: https://catena-x.net/de/standard-library + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- The Traceability KIT and sub-KITs will include further information on data asset structures, Digital Twin Submodel examples and API calls to be made. + +- [SMT] How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf + +- CX Operating Model [https://catena-x.net/fileadmin/\_online\_media\_/CX\_Operating\_Modelv2.1_final.pdf](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf) + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_Notification-State-Model.drawio.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_Notification-State-Model.drawio.svg new file mode 100644 index 000000000..319529581 --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_Notification-State-Model.drawio.svg @@ -0,0 +1,4 @@ + + + +
    ONLY by the Sender
    CREATED
    with Http Status Code 201
    ONLY by the Sender
    SENT
    ONLY by the Sender
    RECEIVED
    ONLY by the Sender
    ACKNOWLEDGED
    ONLY by the Sender
    ACCEPTED
    ONLY by the Sender
    DECLINED
    X
    CLOSED
    X
    Legend
    Sender
    Receiver
     \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_Notification-State-Model.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_Notification-State-Model.svg new file mode 100644 index 000000000..319529581 --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_Notification-State-Model.svg @@ -0,0 +1,4 @@ + + + +
    ONLY by the Sender
    CREATED
    with Http Status Code 201
    ONLY by the Sender
    SENT
    ONLY by the Sender
    RECEIVED
    ONLY by the Sender
    ACKNOWLEDGED
    ONLY by the Sender
    ACCEPTED
    ONLY by the Sender
    DECLINED
    X
    CLOSED
    X
    Legend
    Sender
    Receiver
     \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_ReceiveQuality_6.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_ReceiveQuality_6.svg new file mode 100644 index 000000000..661f9ae7f --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_ReceiveQuality_6.svg @@ -0,0 +1 @@ +SenderReceiverSome (Traceability) AppSome (Traceability) AppNotification EDC AdapterNotification EDC AdapterEDCEDCDiscovery ServiceDiscovery ServiceEDCEDCSome (Traceability) AppSome (Traceability) AppNot mandatory as the interactionwith the EDC can be implementedalso in the (Traceability) App. However, a similar functionality(e.g., fetch catalog)- as shown below - must beprovided.[01]Create EDC Asset for"Quality Investigation Resolve"withDataAddressasHTTP POSTendpoint[02]OK[03]Trigger Resolution of Notification[04]Resolve EDC EndpointBPN of supply chain partner (as given in existing notification)[05]OK[06]Send NotificationResolutionPayload as described above.[07]Fetch Catalog[08]Fetch Catalog[09]Find and Select ContractFind the correct contract offer with: "asset:prop:notificationtype": "qualityinvestigation","asset:prop:notificationmethod": "resolve"[10]Intiatiate Contract Negotiation[11]Contract Negotiation[12]Inititate Data Transfer[13]Establish Channel[14]POST /public/...Payload as described above.[15]POST /public/...Payload as described above.[16]POST /notifications/qualityinvestigations/resolvePayload as described above.The http path depends on the DataAddressin the EDC Data Asset. Thus, it depends on the(Trace) app.[17]200OKPayload as described above.[18]200OKPayload as described above.[19]200OKPayload as described above.[20]200OKPayload as described above. \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_Receive_7.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_Receive_7.svg new file mode 100644 index 000000000..afa05ed18 --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_Receive_7.svg @@ -0,0 +1 @@ +SenderReceiverSome (Traceability) AppSome (Traceability) AppNotification EDC AdapterNotification EDC AdapterEDCEDCDiscovery ServiceDiscovery ServiceEDCEDCSome (Traceability) AppSome (Traceability) AppNot mandatory as the interactionwith the EDC can be implementedalso in the (Traceability) App. However, a similar functionality(e.g., fetch catalog)- as shown below - must beprovided.[01]Create EDC Asset for"Quality Alert Resolve"withDataAddressasHTTP POSTendpoint[02]OK[03]Trigger Resolution of Notification[04]Resolve EDC EndpointBPN of supply chain partner (as given in existing notification)[05]OK[06]Send NotificationResolutionPayload as described above.[07]Fetch Catalog[08]Fetch Catalog[09]Find and Select ContractFind the correct contract offer with: "asset:prop:notificationtype": "qualityalert","asset:prop:notificationmethod": "resolve"[10]Intiatiate Contract Negotiation[11]Contract Negotiation[12]Inititate Data Transfer[13]Establish Channel[14]POST /public/...Payload as described above.[15]POST /public/...Payload as described above.[16]POST /notifications/qualityalerts/resolvePayload as described above.The http path depends on the DataAddressin the EDC Data Asset. Thus, it depends on the(Trace) app.[17]200OKPayload as described above.[18]200OKPayload as described above.[19]200OKPayload as described above.[20]200OKPayload as described above. \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_SendAndReceive_2.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_SendAndReceive_2.svg new file mode 100644 index 000000000..783def39a --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_SendAndReceive_2.svg @@ -0,0 +1 @@ +SenderReceiverSome (Traceability) AppSome (Traceability) AppNotification EDC AdapterNotification EDC AdapterEDCEDCDiscovery ServiceDiscovery ServiceEDCEDCSome (Traceability) AppSome (Traceability) AppNot mandatory as the interactionwith the EDC can be implementedalso in the (Traceability) App. However, a similar functionality(e.g., fetch catalog)- as shown below - must beprovided.[01]Create EDC Asset for"Quality Investigation Receipt"withDataAddressasHTTP POSTendpoint[02]OK[03]Identify Suspect Part(s) / Batch(es)[04]Identify BPN for Suspect Part(s) / Batch(es)[05]Create NotificationStatus := CREATED[06]Resolve EDC EndpointBPN of supect part(s) / batch(es)[07]OK[08]Update Notification StatusStatus := SENT[09]Send NotificationReceiptPayload as described above.[10]Fetch Catalog[11]Fetch Catalog[12]Find and Select ContractFind the correct contract offer with: "asset:prop:notificationtype": "qualityinvestigation","asset:prop:notificationmethod": "receive"[13]Intiatiate Contract Negotiation[14]Contract Negotiation[15]Inititate Data Transfer[16]Establish Channel[17]POST /public/...Payload as described above.[18]POST /public/...Payload as described above.[19]POST /notifications/qualityinvestigations/receivePayload as described above.The http path depends on the DataAddressin the EDC Data Asset. Thus, it depends on the(Trace) app.[20]201OK[21]201OK[22]201OK[23]201OK[24]Update Notification StatusStatus := RECEIVED \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_SendAndReceive_3.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_SendAndReceive_3.svg new file mode 100644 index 000000000..6cde27a78 --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_SendAndReceive_3.svg @@ -0,0 +1 @@ +SenderReceiverSome (Traceability) AppSome (Traceability) AppNotification EDC AdapterNotification EDC AdapterEDCEDCDiscovery ServiceDiscovery ServiceEDCEDCSome (Traceability) AppSome (Traceability) AppNot mandatory as the interactionwith the EDC can be implementedalso in the (Traceability) App. However, a similar functionality(e.g., fetch catalog)- as shown below - must beprovided.[01]Create EDC Asset for"Quality Alert Receipt"withDataAddressasHTTP POSTendpoint[02]OK[03]Identify Defective Part(s) / Batch(es)[04]Identify BPN for Defective Part(s) / Batch(es)[05]Create NotificationStatus := CREATED[06]Resolve EDC EndpointBPN of defective part(s) / batch(es)[07]OK[08]Update Notification StatusStatus := SENT[09]Send NotificationReceiptPayload as described above.[10]Fetch Catalog[11]Fetch Catalog[12]Find and Select ContractFind the correct contract offer with: "asset:prop:notificationtype": "qualityalert","asset:prop:notificationmethod": "receive"[13]Intiatiate Contract Negotiation[14]Contract Negotiation[15]Inititate Data Transfer[16]Establish Channel[17]POST /public/...Payload as described above.[18]POST /public/...Payload as described above.[19]POST /notifications/qualityalerts/receivePayload as described above.The http path depends on the DataAddressin the EDC Data Asset. Thus, it depends on the(Trace) app.[20]201OK[21]201OK[22]201OK[23]201OK[24]Update Notification StatusStatus := RECEIVED \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_UpdateQualityAlert_5.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_UpdateQualityAlert_5.svg new file mode 100644 index 000000000..0231cb82f --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_UpdateQualityAlert_5.svg @@ -0,0 +1 @@ +SenderReceiverSome (Traceability) AppSome (Traceability) AppNotification EDC AdapterNotification EDC AdapterEDCEDCDiscovery ServiceDiscovery ServiceEDCEDCSome (Traceability) AppSome (Traceability) AppNot mandatory as the interactionwith the EDC can be implementedalso in the (Traceability) App. However, a similar functionality(e.g., fetch catalog)- as shown below - must beprovided.[01]Create EDC Asset for"Quality Alert Update"withDataAddressasHTTP POSTendpoint[02]OK[03]Change Notification(e.g., Status according Status Model)[04]Resolve EDC EndpointBPN of supply chain partner (as given in existing notification)[05]OK[06]Send NotificationUpdatePayload as described above.[07]Fetch Catalog[08]Fetch Catalog[09]Find and Select ContractFind the correct contract offer with: "asset:prop:notificationtype": "qualityalert","asset:prop:notificationmethod": "update"[10]Intiatiate Contract Negotiation[11]Contract Negotiation[12]Inititate Data Transfer[13]Establish Channel[14]POST /public/...Payload as described above.[15]POST /public/...Payload as described above.[16]POST /notifications/qualityalerts/updatePayload as described above.The http path depends on the DataAddressin the EDC Data Asset. Thus, it depends on the(Trace) app.[17]200OK[18]200OK[19]200OK[20]200OK \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_UpdateQuality_4.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_UpdateQuality_4.svg new file mode 100644 index 000000000..22f8711bf --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_UpdateQuality_4.svg @@ -0,0 +1 @@ +SenderReceiverSome (Traceability) AppSome (Traceability) AppNotification EDC AdapterNotification EDC AdapterEDCEDCDiscovery ServiceDiscovery ServiceEDCEDCSome (Traceability) AppSome (Traceability) AppNot mandatory as the interactionwith the EDC can be implementedalso in the (Traceability) App. However, a similar functionality(e.g., fetch catalog)- as shown below - must beprovided.[01]Create EDC Asset for"Quality Investigation Update"withDataAddressasHTTP POSTendpoint[02]OK[03]Change Notification(e.g., Status according Status Model)[04]Resolve EDC EndpointBPN of supply chain partner (as given in existing notification)[05]OK[06]Send NotificationUpdatePayload as described above.[07]Fetch Catalog[08]Fetch Catalog[09]Find and Select ContractFind the correct contract offer with: "asset:prop:notificationtype": "qualityinvestigation","asset:prop:notificationmethod": "update"[10]Intiatiate Contract Negotiation[11]Contract Negotiation[12]Inititate Data Transfer[13]Establish Channel[14]POST /public/...Payload as described above.[15]POST /public/...Payload as described above.[16]POST /notifications/qualityinvestigations/updatePayload as described above.The http path depends on the DataAddressin the EDC Data Asset. Thus, it depends on the(Trace) app.[17]200OK[18]200OK[19]200OK[20]200OK \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_notification_architecture_level_1.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_notification_architecture_level_1.svg new file mode 100644 index 000000000..096533700 --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/CX0125_notification_architecture_level_1.svg @@ -0,0 +1,4 @@ + + + +

    Catena-X Core Services
    «Catena-X Partner»
    Traceability at Another Catena-X Partner
    «Catena-X Partner»
    Traceability at Catena-X Partner
    DTR via EDC:
    Lookup Digital Twins for Catena-X Partners

    Register Submodels
     as EDC Assets

    Process requests for
    EDC Assets

    Register Unique ID Push Topics
    as EDC Assets

    Receive and send
    Unique ID Push notifications
    Register Digital Twins 
    Lookup EDC adress
    for Catena-X partners
    «Component»
    Data Provisioning
    Fetch Data from Digital Twins 
    Optionally: Lookup Digital Twins
    «Component»
    Traceability App
    «Service»
    Eclipse Dataspace
    Connector
    (EDC)
    Internal Systems
    «Service»
    Eclipse Dataspace
    Connector
    (EDC)
    Optional: 

    «Service»
    Item Relationship Service
    (IRS)
    Internal Systems
    «Service»
    EDC Discovery
    «Service»
    Digital Twin Registry
    «Service»
    Digital Twin Registry
    DTR via EDC:
    Lookup Digital Twins for Catena-X Partners

    Register Quality Investigation & Alert Topics
    as EDC Assets

    Receive and send
     Quality Investigation & Alert notifications

    Optionally: Fetch Data from Digital Twins 
    Lookup EDC adress
    for Catena-X partners
     \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_send-receive-alert.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_send-receive-alert.svg new file mode 100644 index 000000000..0b6aae5af --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_send-receive-alert.svg @@ -0,0 +1 @@ +SenderReceiverSome (Traceability) AppSome (Traceability) AppNotification EDC AdapterNotification EDC AdapterEDCEDCDiscovery ServiceDiscovery ServiceEDCEDCSome (Traceability) AppSome (Traceability) AppNot mandatory as the interactionwith the EDC can be implementedalso in the (Traceability) App. However, a similar functionality(e.g., fetch catalog)- as shown below - must beprovided.[01]Create EDC Asset for"Quality Alert Receipt"withDataAddressasHTTP POSTendpoint[02]OK[03]Identify Defective Part(s) / Batch(es)[04]Identify BPN for Defective Part(s) / Batch(es)[05]Create NotificationStatus := CREATED[06]Resolve EDC EndpointBPN of defective part(s) / batch(es)[07]OK[08]Update Notification StatusStatus := SENT[09]Send NotificationReceiptPayload as described above.[10]Fetch Catalog[11]Fetch Catalog[12]Find and Select ContractFind the correct contract offer with: "dct:type": {"@id": "cx-taxo:ReceiveQualityAlertNotification"}"[13]Intiatiate Contract Negotiation[14]Contract Negotiation[15]Inititate Data Transfer[16]Establish Channel[17]POST /public/...Payload as described above.[18]POST /public/...Payload as described above.[19]POST /notifications/qualityalerts/receivePayload as described above.The http path depends on the DataAddressin the EDC Data Asset. Thus, it depends on the(Trace) app.[20]201OK[21]201OK[22]201OK[23]201OK[24]Update Notification StatusStatus := RECEIVED \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_send-receive.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_send-receive.svg new file mode 100644 index 000000000..bbe318cbd --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_send-receive.svg @@ -0,0 +1 @@ +SenderReceiverSome (Traceability) AppSome (Traceability) AppNotification EDC AdapterNotification EDC AdapterEDCEDCDiscovery ServiceDiscovery ServiceEDCEDCSome (Traceability) AppSome (Traceability) AppNot mandatory as the interactionwith the EDC can be implementedalso in the (Traceability) App. However, a similar functionality(e.g., fetch catalog)- as shown below - must beprovided.[01]Create EDC Asset for"Quality Investigation Receipt"withDataAddressasHTTP POSTendpoint[02]OK[03]Identify Suspect Part(s) / Batch(es)[04]Identify BPN for Suspect Part(s) / Batch(es)[05]Create NotificationStatus := CREATED[06]Resolve EDC EndpointBPN of supect part(s) / batch(es)[07]OK[08]Update Notification StatusStatus := SENT[09]Send NotificationReceiptPayload as described above.[10]Fetch Catalog[11]Fetch Catalog[12]Find and Select ContractFind the correct contract offer with: "dct:type": {"@id": "cx-taxo:ReceiveQualityInvestigationNotification"}"[13]Intiatiate Contract Negotiation[14]Contract Negotiation[15]Inititate Data Transfer[16]Establish Channel[17]POST /public/...Payload as described above.[18]POST /public/...Payload as described above.[19]POST /notifications/qualityinvestigations/receivePayload as described above.The http path depends on the DataAddressin the EDC Data Asset. Thus, it depends on the(Trace) app.[20]201OK[21]201OK[22]201OK[23]201OK[24]Update Notification StatusStatus := RECEIVED diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_update-alert.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_update-alert.svg new file mode 100644 index 000000000..877ab2297 --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_update-alert.svg @@ -0,0 +1 @@ +SenderReceiverSome (Traceability) AppSome (Traceability) AppNotification EDC AdapterNotification EDC AdapterEDCEDCDiscovery ServiceDiscovery ServiceEDCEDCSome (Traceability) AppSome (Traceability) AppNot mandatory as the interactionwith the EDC can be implementedalso in the (Traceability) App. However, a similar functionality(e.g., fetch catalog)- as shown below - must beprovided.[01]Create EDC Asset for"Quality Alert Update"withDataAddressasHTTP POSTendpoint[02]OK[03]Change Notification(e.g., Status according Status Model)[04]Resolve EDC EndpointBPN of supply chain partner (as given in existing notification)[05]OK[06]Send NotificationUpdatePayload as described above.[07]Fetch Catalog[08]Fetch Catalog[09]Find and Select ContractFind the correct contract offer with: "dct:type": {"@id": "cx-taxo:UpdateQualityAlertNotification"}"[10]Intiatiate Contract Negotiation[11]Contract Negotiation[12]Inititate Data Transfer[13]Establish Channel[14]POST /public/...Payload as described above.[15]POST /public/...Payload as described above.[16]POST /notifications/qualityalerts/updatePayload as described above.The http path depends on the DataAddressin the EDC Data Asset. Thus, it depends on the(Trace) app.[17]200OK[18]200OK[19]200OK[20]200OK \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_update-investigation.svg b/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_update-investigation.svg new file mode 100644 index 000000000..6e03959cd --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/notification_update-investigation.svg @@ -0,0 +1 @@ +SenderReceiverSome (Traceability) AppSome (Traceability) AppNotification EDC AdapterNotification EDC AdapterEDCEDCDiscovery ServiceDiscovery ServiceEDCEDCSome (Traceability) AppSome (Traceability) AppNot mandatory as the interactionwith the EDC can be implementedalso in the (Traceability) App. However, a similar functionality(e.g., fetch catalog)- as shown below - must beprovided.[01]Create EDC Asset for"Quality Investigation Update"withDataAddressasHTTP POSTendpoint[02]OK[03]Change Notification(e.g., Status according Status Model)[04]Resolve EDC EndpointBPN of supply chain partner (as given in existing notification)[05]OK[06]Send NotificationUpdatePayload as described above.[07]Fetch Catalog[08]Fetch Catalog[09]Find and Select ContractFind the correct contract offer with: "dct:type": {"@id": "cx-taxo:UpdateQualityInvestigationNotification"}"[10]Intiatiate Contract Negotiation[11]Contract Negotiation[12]Inititate Data Transfer[13]Establish Channel[14]POST /public/...Payload as described above.[15]POST /public/...Payload as described above.[16]POST /notifications/qualityinvestigations/updatePayload as described above.The http path depends on the DataAddressin the EDC Data Asset. Thus, it depends on the(Trace) app.[17]200OK[18]200OK[19]200OK[20]200OK \ No newline at end of file diff --git a/docs/standards/CX-0125-TraceabilityUseCase/assets/notifications-1-2-1.yaml b/docs/standards/CX-0125-TraceabilityUseCase/assets/notifications-1-2-1.yaml new file mode 100644 index 000000000..a51422bbd --- /dev/null +++ b/docs/standards/CX-0125-TraceabilityUseCase/assets/notifications-1-2-1.yaml @@ -0,0 +1,340 @@ +openapi: 3.0.1 +info: + title: Notification API + description: Notification API + license: + name: Apache License v2.0 + url: http://apache.org/v2 + version: 1.2.1 +servers: + - url: / +tags: + - name: Notification API + description: 'Api to receive, update and fetch a notification. At the moment, quality notifications are supported. Those support two types of quality notifications: quality investigations and quality alerts.' +paths: + /qualitynotifications/receive: + post: + tags: + - Quality notification + description: Receives a new quality notification + operationId: receiveQualityNotification + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/QualityNotificationReceiveRequestBody' + responses: + "201": + description: Quality notification was received successfully + "400": + description: Request body was malformed + "401": + description: Not authorized + "403": + description: Forbidden + "405": + description: Method not allowed + "409": + description: Could not accept the send quality notification, because a quality notification with that notificationId already exists + "422": + description: Could not accept the send quality notification even though it is syntactically correct. The quality notification is not accepted, because of semantic reasons (e.g., an affected item is not known by the receiver). + /qualitynotifications/update: + post: + tags: + - Quality notification + description: Updates a quality notification + operationId: updateQualityNotification + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/QualityNotificationUpdateRequestBody' + responses: + "200": + description: Quality notification was updated successfully + "400": + description: Request body was malformed + "401": + description: Not authorized + "403": + description: Forbidden + "405": + description: Method not allowed + "404": + description: Could not update the quality notification, because a quality notification with that notificationId does not exist + "422": + description: Could not update the quality notification even though the request is syntactically correct. The quality notification update is not accepted, because of semantic reasons (e.g., status cannot be changed). +components: + schemas: + StandardNotificationHeader: + $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_2.0.0_HeaderCharacteristic' + StandardNotificationConnectToRequestHeader: + allOf: + - $ref: '#/components/schemas/StandardNotificationHeader' + QualityNotificationReceivePayload: + type: object + required: + - notificationId + - status + - severity + - listOfAffectedItems + properties: + notificationId: + type: string + format: uuid + example: "41d743c3-6e8a-4393-88af-10494e50bea9" + description: A message can have several notifications, which are exchanged between the supply chain partners. Each notification shall be identifiable, and thus, has an unique notification id. This notification id is automatically generated for each notification that is sent. Every time a HTTP POST is send a new notification ID is generated. A UUIDv4 to uniquely identify an individual quality notification message. In case of an initial sending of a message the notificationId has to be a newly generated UUIDv4. + status: + $ref: '#/components/schemas/QualityStatus' + severity: + $ref: '#/components/schemas/QualitySeverity' + information: + type: string + maxLength: 1000 + example: "Gear boxes loose oil while driving." + description: A text that e.g. describes the quality alert or the quality investigation. Recommendations or counter actions can be added by the receiver when ACCECPTED or DECLINED the notification. + listOfAffectedItems: + type: array + items: + type: string + example: + - "urn:uuid:57e4e3c1-a6f0-46a0-90df-1fb17cbc157d" + - "urn:uuid:e4da568b-8cf1-4f5f-a96a-cf26265b2c72" + description: Items are added by the initiator (i.e., sender) of a notification. Once the notification is not in the status CREATED (e.g., it has been sent) the array cannot be changed. + QualityNotificationUpdatePayload: + required: + - notificationId + type: object + properties: + notificationId: + type: string + format: uuid + example: "41d743c3-6e8a-4393-88af-10494e50bea9" + description: A message can have several notifications, which are exchanged between the supply chain partners. Each notification shall be identifiable, and thus, has an unique notification id. This notification id is automatically generated for each notification that is sent. Every time a HTTP POST is send a new notification ID is generated. A UUIDv4 to uniquely identify an individual quality notification message. In case of an initial sending of a message the notificationId has to be a newly generated UUIDv4. + status: + $ref: '#/components/schemas/QualityStatus' + severity: + $ref: '#/components/schemas/QualitySeverity' + information: + type: string + maxLength: 1000 + example: "Gear boxes loose oil while driving." + description: A text that e.g. describes the quality alert or the quality investigation. Recommendations or counter actions can be added by the receiver when ACCECPTED or DECLINED the notification. + QualityNotificationReceiveRequestBody: + required: + - header + - content + type: object + properties: + header: + $ref: '#/components/schemas/StandardNotificationConnectToRequestHeader' + content: + $ref: '#/components/schemas/QualityNotificationReceivePayload' + QualityNotificationUpdateRequestBody: + required: + - header + - content + type: object + properties: + header: + $ref: '#/components/schemas/StandardNotificationConnectToRequestHeader' + content: + $ref: '#/components/schemas/QualityNotificationUpdatePayload' + QualitySeverity: + type: string + enum: + - MINOR + - MAJOR + - CRITICAL + - LIFE-THREATENING + example: CRITICAL + description: The severity of the quality notification describes its criticality. The severity is set by the initiator of a quality notification. The following entries are supported and allowed + + + - MINOR + This is the case if the quality issue(s) is/are not affecting any functionalities of the serialized parts/batch e.g., aesthetical issue. + + + - MAJOR + This is the case if the quality issue(s) is/are so critical that the functionality of the serialized parts/batch is partially not given. This is also the case if the serialized part / batch is no longer functional, but the missing functionality + + (a) can be compensated by other parts of a superordinate system or + (b) has a relatively low significance / benefit + + + - CRITICAL + This is the case if the quality issue(s) is/are so critical that the basic functionality of the serialized parts/batch is no longer given. + + + - LIFE-THREATENING + This is the case if the quality issue(s) is/are so critical that it even endangers human lives e.g., the airbag or break is not working. + QualityStatus: + type: string + enum: + - CREATED + - SENT + - RECEIVED + - ACKNOWLEDGED + - ACCEPTED + - DECLINED + - CLOSED + example: SENT + description: The status of the quality notification. The following entries are supported and allowed + + + - CREATED + This status is an internal status and is used after the initial creation of a notification. It is not communicated to an other CX/business partner. + + + - SENT + This status means that the notification has been sent out. This status is shown on the sender side (and not on the receiver side). + + + - RECEIVED + This status means that the notification has been received by the receiver. The status is shown on sender and receiver side. It is not communicated to an other CX/business partner. + + + - ACKNOWLEDGED + Defines that a user has confirmed that the notification has been received. This does NOT mean that the user accepted the notification in the sense of an admission of guilt or the like. However, it means that the notification gets processed by the user (or the organization behind). + + + - ACCEPTED + The status expresses that the received agrees on the quality investigation/alert. Recommendations, counter actions, and the like can be conveyed in the payload field information. + + + - DECLINED + The status expresses that the received does not agree on the quality investigation/alert. Recommendations, counter actions, and the like can be conveyed in the payload field information. + + + - CLOSED + This status is set by the initiator of the notification either to regularly close the notification (i.e., after the receiver has set the status to ACCEPTED or DECLINED) or to abort the processing of the notification (e.g., because the notification is not relevant anymore). + # ----------------------------------------- + # Schema: io.catenax.shared.message_header + # ----------------------------------------- + urn_samm_io.catenax.shared.uuid_1.0.0_UuidV4Trait: + type: string + description: "The provided regular expression ensures that the UUID is composed\ + \ of five groups of characters separated by hyphens, in the form 8-4-4-4-12\ + \ for a total of 36 characters (32 hexadecimal characters and 4 hyphens),\ + \ optionally prefixed by \"urn:uuid:\" to make it an IRI." + pattern: "(^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)|(^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)" + urn_samm_io.catenax.shared.message_header_2.0.0_ContextCharacteristic: + type: string + enum: + - Traceability-QualityNotification-Investigation:2.0.0 + - Traceability-QualityNotification-Alert:2.0.0 + description: The context defines the type of quality notification. The context is chosen by the initiator of a quality notification. The QM-Investigation describes a quality issue top-down when it's sent towards the supplier. The QM-Alert describes a quality issue bottom-up when it's sent towards the customer. + + + Traceability-QualityNotification-Investigation:2.0.0 + + + A quality investigation is used to try and technically narrow down the cause of a suspected problem with a serialized part / batch. To achieve this, a customer who has purchased serialized parts/ batches can request his supplier to investigate the affected serialized parts / batches regarding the suspected problem. + + + Traceability-QualityNotification-Alert:2.0.0 + + + A quality alert is sent by a supplier to a customer and describes identified quality issue(s) in one or more serialized parts/ batches delivered to that customer. Thus, the quality alert - besides other information - contains a list of the affected serialized parts/ batches and a description of the quality issue(s). In the worst case the quality alert can result in a recall of the affected serialized parts/ batches. + + + The value MUST consist of two parts -- an identifier of the context (e.g. business domain, etc.) followed by a version number. Both the identifier and the version number MUST correspond to the content of the message. Versioning only refers to major versions in both default and fallback cases. Note -- The version of the message's header is specified in the version field. + example: "Traceability-QualityNotification-Alert:2.0.0" + urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp: + type: string + pattern: "-?([1-9][0-9]{3,}|0[0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T(([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\\ + .[0-9]+)?|(24:00:00(\\.0+)?))(Z|(\\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))?" + description: Describes a Property which contains the date and time with an optional + timezone. + example: "2007-08-31T16:47+00:00" + urn_samm_io.catenax.shared.business_partner_number_1.0.0_BpnlTrait: + type: string + description: "The provided regular expression ensures that the BPNL is composed\ + \ of prefix 'BPNL', 10 digits and two uppercase letters." + pattern: "^BPNL[0-9]{8}[a-zA-Z0-9]{4}$" + urn_samm_io.catenax.shared.message_header_2.0.0_SemanticVersioningTrait: + type: string + description: Constraint for defining a SemVer version. + pattern: "^(0|[1-9][0-9]*).(0|[1-9][0-9]*).(0|[1-9][0-9]*)(-(0|[1-9A-Za-z-][0-9A-Za-z-]*)(.[0-9A-Za-z-]+)*)?([0-9A-Za-z-]+(.[0-9A-Za-z-]+)*)?$" + example: "urn:samm:io.catenax.shared.message_header:3.0.0#MessageHeaderAspect" + urn_samm_io.catenax.shared.message_header_2.0.0_HeaderCharacteristic: + description: Characteristic describing the common shared aspect Message Header + type: object + properties: + messageId: + description: Unique ID identifying the message. The purpose of the ID is\ + \ to uniquely identify a single message, therefore it MUST not be reused. + + In case of traceability quality notifications this means the following. + + A UUIDv4 to uniquely identify a quality notification. This unique ID gets generated by the initiator of a quality notification. The sender and receiver of a quality notification use this unique ID to reference a quality notification. + $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_1.0.0_UuidV4Trait' + context: + description: |- + Information about the context the message should be considered in. + The value MUST consist of two parts: an identifier of the context (e.g. business domain, etc.) followed by a version number. + Both the identifier and the version number MUST correspond to the content of the message. + If the content of a message is described by an aspect model available in the Catena-X Semantic Hub, then the unique identifier of this semantic model (e.g. urn:samm:io.catenax.:1.x.x) MUST be used as a value of the context field. This is considered the default case. + In all other cases the value of the context field MUST follow the pattern --:<[major] version> (e.g. Traceability-QualityNotification-Alert:2.x.x). + Versioning only refers to major versions in both default and fallback cases. + Note: The version of the message's header is specified in the version field. + $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_2.0.0_ContextCharacteristic' + sentDateTime: + description: Time zone aware timestamp holding the date and the time the + message was sent by the sending party. The value MUST be formatted according + to the ISO 8601 standard + $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp' + senderBpn: + description: The Business Partner Number of the sending party. The value + MUST be a valid BPN. BPNA and BPNS are not allowed. Applicable constraints + are defined in the corresponding standard + $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_1.0.0_BpnlTrait' + receiverBpn: + description: The Business Partner Number of the receiving party. The value + MUST be a valid BPN. BPNA and BPNS are not allowed. Applicable constraints + are defined in the corresponding standard. + $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_1.0.0_BpnlTrait' + expectedResponseBy: + description: Time zone aware timestamp holding the date and time by which + the sending party expects a certain type of response from the receiving + party. The meaning and interpretation of the fields's value are context-bound + and MUST therefore be defined by any business domain or platform capability + making use of it. The value MUST be formatted according to the ISO 8601 + standard + $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp' + relatedMessageId: + description: Unique ID identifying a message somehow related to the current + one + + In case of traceability quality notifications this means the following. + + A UUIDv4 to uniquely identify a related quality notification. This field is not about mapping the internal references between quality notifications. This field should only reference the quality notifications that + + + (a) the recipient can basically understand in his business context and + + + (b) that are of concern to the recipient + + + That means, that in most instances, the sender and receiver of both quality notifications (i.e., the send one and the referenced one) are the same. + + + Example + + + Due to an QM-Investigation an QM-Alert is created and referencing to the QM-Investigation. + An QM-Investigation is followed by another QM-Investigation that is referencing to the same quality issue. + $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_1.0.0_UuidV4Trait' + version: + description: The unique identifier of the aspect model defining the structure + and the semantics of the message's header. The version number should reflect + the versioning schema of aspect models in Catena-X. + $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_2.0.0_SemanticVersioningTrait' + required: + - messageId + - context + - sentDateTime + - senderBpn + - receiverBpn + - version diff --git a/docs/standards/CX-0126-IndustryCorePartType/CX-0126-IndustryCorePartType.md b/docs/standards/CX-0126-IndustryCorePartType/CX-0126-IndustryCorePartType.md new file mode 100644 index 000000000..3b047cf8d --- /dev/null +++ b/docs/standards/CX-0126-IndustryCorePartType/CX-0126-IndustryCorePartType.md @@ -0,0 +1,638 @@ +# CX-0126 Industry Core: Part Type 2.0.0 + +## ABSTRACT + +This standard describes the **Industry Core: Part Type**. It sets the foundation to describe, identify and find a component on a type level and enables traversing across several levels to ensure the creation of data chains. The core makes it possible to configure enablement services for component-based data exchange. Other use cases are meant to build upon the foundation that is given by the industry core. + +## FOR WHOM IS THE STANDARD DESIGNED + +This standard is designed for everybody who wants to register, describe and use digital twins on part type level. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +- Added new content in [Section 2.1.3](#213-additional-requirements) + - New paragraph "Conventions for Use Case Policy in context data exchange" + - Notes for versioning + +- Changes in specificAssetIds of Digital Twins in [Section 2.1.4](#214-digital-twins-and-specific-asset-ids): + - removed assetLifeCyclePhase + - digitalTwinType is now mandatory (before it was optional) + +- Replaced standardized aspect model in [Section 3.1](#31-aspect-model-parttypeinformation): + - removed PartAsPlanned 2.0.0 + - replaced with newly standardized PartTypeInformation 1.0.0 (see link to changelog in section of the aspect model) + +- New version of aspect model in [Section 3.2](#32-aspect-model-singlelevelbomasplanned): + - SingleLevelBomAsPlanned 3.0.0 (see link to changelog in section of the aspect model) + +- Newly standardized aspect model in [Section 3.3](#33-aspect-model-singlelevelusageasplanned): + - SingleLevelUsageAsPlanned 2.0.0 (see link to changelog in section of the aspect model) + +- Added Unique ID Push Notification API in [Section 4.1](#41-unique-id-push-notification-api) as content of the industry core + +- Deleted "Every certified business application relying on aspects models of this standard **MUST** be able to consume data conformant to the semantic models specified in this document." from [Section 3](#3-aspect-models) + +**Note:** This release (24.05.) contains **breaking changes**! + +## 1 INTRODUCTION + +This standard contains all information on the **Industry Core: Part Type**. The Industry Core is a shared foundation for use cases that utilize digital twins and aspect models in Catena-X. The Industry Core: Part Type describes digital twins and aspect models that are used to represent identifiable non-instanced parts, such as catalog parts. Digital twins and aspect models are meant to be reused by other use cases as much as possible, in order to simplify data provisioning across different use cases. + +The Industry Core: Part Type provides the basis for identification, description, findability of part type digital twins in the Catena-X network and the connection of those twins to build data chains across the supply chain. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This document is targeting subsets of the following roles: + +- Data Provider / Consumer +- Business Application Provider +- Enablement Service Provider + +**Note:** Fulfilling a use-case standard by a data provider / consumer can be done in two ways: + +1. Purchase a certified app for the use-case. In this case the data provider / consumer does not need to proof conformity again and +2. Data Provisioning / Consumption without a certified app for the use-case. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +The aim of the Industry Core: Part Type is to build the foundation to describe, identify and find a component on an type level and to enable traversing across the levels of the supply chain in both directions to ensure the creation of data chains and enable data driven use cases over all n-tier levels without compromising data sovereignty. This standard enables data and app providers to deliver solutions for building data chains for identifiable non-instanced parts, such as catalogue parts. This is achieved via the standardized creation of digital twins of those entities as well as the logical linking to their parent and child components (Bill of Material as Planned, Usage as Planned). + +The Industry Core: Part Type is not intended to include all information that may be needed in a use case. Instead, it allows the establishment of a value driven data chain and serves as a basis for further data driven use cases. It enables data owners to provide necessary data with individual access rights and usage restrictions (access and usage policies) to ensure privacy and security. Additional information might be shared by utilizing the Asset Administration Shell through additional aspects or submodels. + +The Industry Core: Part Type is supporting the availability of data of identifiable non-instanced parts and the connection to their parent and child parts. It describes the concrete digital reflection of a generic (not physically produced) part on material- or catalog-level and its provisioning towards Catena-X including Interoperability and Data Sovereignty standards and components by the participants willing to share such data. This standard also defines which components (e.g. Digital Twin Registry, IDS compliant Connector) must be used in order to be interoperable and sovereign in a data exchange as defined in Catena-X. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +All sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +All participants* and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). Please refer to: https://catena-x.net/en/catena-x-introduce-implement/certification for the process of conformity assessment and certification. + +The specific criteria described in this document are describing the usage of the central tools as well as common tools described in the linked standardization documents and therefore compliance should be checked with the tools provided for these components. + +The versions of the standardization documents valid for this standard are mentioned in sections where the [standalone standards](#211-list-of-standalone-standards), [normative references](#61-normative-references) and [non-normative references](#62-non-normative-references) are listed. The valid versions are not specifically mentioned in the body text. + +*Disclaimer: The operating model released by the Catena-X association will define the roadmap, content and scope for the certification process. This will include the roles, certification and further assessment procedures as well as the rollout phases.* + +### 1.4 EXAMPLES + +Examples for data models: See according subsection [3 Aspect Models](#3-aspect-models). + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +**Aspect Model** + +A formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect. + +An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model. Aspect models are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +**Asset Administration Shell (AAS)** +The Asset Administration Shell is a digital representation of an asset. It is a form of a digital twin. + +**Business Partner Number (BPN)** +A BPN is the unique identifier of a partner within Catena. + +**Tractus-X Eclipse Dataspace Connector (Tractus-X EDC)**: +The Tractus-X EDC is a reference implementation for a connector conformant to CX-0018 currently acting as a de-facto standard and/or reference Implementation within Catena-X. When mentioning the Tractus-X EDC in this standard, any other CX-0018 conformant connector is also a valid option. + +**IDSA/IDSA Protocol** +Protocol being used for data exchange in an International Dataspace. This includes contract negotiation. + +**International Data Space (IDS)** +International Data Space and its protocol for data exchange foresees a compliant connector handling contract negotiations before each data transfer and defines a general architecture for data exchange. + +**Part Instance** +A part instance is a physically produced instance (e.g. serialized part, batch, just-in-sequence-part) of a part type. + +**Part Type** +A part type is a generic (not physically produced) part on material- or catalog-level as a representation for a designed part. + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 DATA PROVISIONING INDUSTRY CORE: PART TYPE + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +To participate in Data Provisioning in the Industry Core: Part Type, the following single standards **MUST** be fulfilled by all participants for which the standard is relevant: + +- CX-0002 Digital Twins in Catena-X 2.2.0 +- CX-0018 Dataspace Connectivity 3.0.0 +- CX-0045 Data Chain Template 1.3.0 + +#### 2.1.2 DATA REQUIRED + +A digital twin **MAY** be created for part types developed by a manufacturer within Catena-X. +The digital twin **MUST** be provisioned as an Asset Administration Shell as per CX-0002 and registered in a decentral Digital Twin Registry hosted by each CX member as described in CX-0002. + +The aspect model "PartTypeInformation" **MUST** be attached to the Asset Administration Shell of each part type, describing a part (e.g. catalog part). + +The aspect model "SingleLevelBomAsPlanned" **MAY** be linked to the Asset Administration Shell of each catalog part holding the information on part relationships top-down on catalog part level. Information on the Bill of Material of those catalog parts **MUST NOT** be provided in any other way than with the aspect model "SingleLevelBomAsPlanned". + +The aspect model "SingleLevelUsageAsPlanned" **MAY** be linked to the Asset Administration Shell of each catalog part holding the information on usage of this part in to be assembled or produced catalog products. Information on the usage of those catalog parts **MUST NOT** be provided in any other way than with the aspect model "SingleLevelUsageAsPlanned". + +The submodel data **MUST** be transferred using the IDS Protocol as described in CX-0018. +The Tractus-X EDC as a reference implementation is **RECOMMENDED** to be used as a connector conformant to CX-0018. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +As the IDS protocol is being used, data **MUST NOT** be transferred before a corresponding contract negotiation has been successfully passed by the participants of the data exchange and a valid contract is present as described in CX-0018. The required data offers **MUST** be discoverable through the Digital Twin Registry as submodel endpoints. + +##### Conventions for Use Case Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +##### Additional Details regarding Access Policies + +A Data Provider **MAY** tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +##### Additional Details regarding Usage Policies + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +##### Versioning + +The Aspect Models that are deployed as Digital Twins **MUST** be published in dcat:Dataset (http://www.w3.org/ns/dcat#) in the property that holds the full URN of the Aspect Model https://admin-shell.io/aas/3/0/HasSemantics/semanticId. Versions are explicitly contained in the URN. + +The API versions **MUST** be published in the property https://w3id.org/catenax/ontology/common#version as version X.Y in dcat:Dataset (http://www.w3.org/ns/dcat#). + +**Note:** Data Assets differentiated only by major version **MUST** be offered in parallel. The current standard and API versions mark the start of Life Cycle Management in Catena-X operations. Previous versions are dismissed. + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +The asset's globalAssetId **MUST** be equal to the unique id used in Catena-X + +The following specific asset IDs not marked as optional **MUST** be available when registering a digital twin or when adding the above mentioned submodels to an existing twin for a part type in order to allow discovery. (see CX-0002 that provides additional information), while `customerPartId` is **RECOMMENDED** to be added to the twin whenever possible, as customers usually do not have access to the manufacturer part number in their logistics processes. The specific asset IDs marked as optional **MAY** be used in addition. + +The following conventions for specific Asset IDs apply to all digital twins: + + + + + + + + + + + + + + + + + + + + + + + + +
    Key Availability Description Type
    manufacturerId Mandatory The Business Partner Number (BPNL) of the manufacturer of the part. BPNL
    manufacturerPartId Mandatory The ID of the type/catalog part from the ***manufacturer***. String
    customerPartId Optional The ID of the type/catalog part from the ***customer***.

    The main reason why this property is optional is that it cannot be guaranteed that every manufacturer knows the customerPartId for their parts. If known, it is ***recommended*** to always add the customerPartId for easier lookup.    		 String
    digitalTwinType Mandatory The types of the digital twins: +
    • "PartInstance" for serialized parts, batches, and JIS parts
    • "PartType" for catalog parts
    DigitalTwinType was added to allow data consumers to search for all digital twins of a particular type, e.g, only for catalog parts by using `digitalTwinType="PartType"` as filter. Without this filter, a search for a particular manufacturer part ID would not only return the digital twin of the catalog part, but also all digital twins of instances of this catalog part, i.e., of the corresponding serial parts.    		 String
    + +##### Authorization: Visbility of Specific Asset IDs in the DTR + +To enforce a strict need-to-know principle (and prevent data from being exposed to non-authorized parties), the visibility of entries in the attribute `specificAssetIds` must be protected, i.e.,their visibility must be restricted to only the manufacturer of the part (which is represented by the digital twin) and the customers of the part. For more information on the semantics of the mentioned properties, see AAS Pt. 1. For more information on the use of Digital Twins in Catena-X, see CX - 0002 [Catena-X Standard Library](https://catena-x.net/de/standard-library). + +## 3 ASPECT MODELS + +> *This section is normative* + +Relevant semantic models of this standard are: + +- [PartTypeInformation](#31-aspect-model-parttypeinformation) +- [SingleLevelBomAsPlanned](#32-aspect-model-singlelevelbomasplanned) +- [SingleLevelUsageAsPlanned](#33-aspect-model-singlelevelusageasplanned) + +Semantic models **MAY** be used individually or together. + +Semantic models **MUST** be made available in the central Semantic Hub. + +Data consumers and data provider **MUST** comply with the license of the semantic models. The submodel data **MUST** be requested and exchanged via a CX-0018 and CX-0002 compliant connector (e.g. Ecplise Dataspace Connector). + +Data providers **MUST** provide data as part of a digital twin of the asset for serialized parts conformant to CX – 0002 DIGITAL TWINS IN CATENA-X. + +The JSON Payloads of data providers **MUST** be conformant to the JSON Schemas as specified in this document. +The unique identifier of the semantic model specified in this document **MUST** be used by the data provider to define the semantics of the data being transferred. + +### 3.1 ASPECT MODEL "PartTypeInformation" + +#### 3.1.1 INTRODUCTION + +This semantic model describes a part/material at type level. The original intent is to attach this aspect to a material-specific twin in an Asset Administration Shell but is not limited to that use case. The aspect allows several identifications: of a component from a manufacturer ID and/or part type and optionally a validity period in order to determine the unique ID with which the part is identified within Catena-X at a given time. + +**Note:** The Aspect model PartTypeInformation **v1.0.0** is **mandatory**. Versions higher than that are **optional**, but might become mandatory in future releases of this standard. For the changelog of the aspect model, [see here](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.part_type_information/RELEASE_NOTES.md). + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#62-non-normative-references). + +The aspect model PartTypeInformation v1.0.0 is written in SAMM 2.1.0 as a modeling language conformant to *CX-0003 SAMM Semantic Aspect Meta Model* as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003. + +#### 3.1.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group Industry Core. This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons[^2]. + +The license information is available in GitHub. In case of doubt the license, copyright and authors information in github overwrites the information in this specification document. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model PartTypeInformation **v1.0.0** has the unique identifier: + +```text +urn:samm:io.catenax.part_type_information:1.0.0#PartTypeInformation +``` + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. This can be viewed by following link: + +- [PartTypeInformation (v1.0.0)](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.part_type_information/1.0.0/PartTypeInformation.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework[^3] is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.1.5.3 AASX + +A AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a submodel template specification conformant to [SMT](#62-non-normative-references). + +**Note:** As soon as the specification v3.0 of the Asset Administration Shell specification is available and update will be provided. + +#### 3.1.6 EXAMPLE DATA + +Example JSON payload: Submodel "PartTypeInformation" v1.0.0 that is **mandatory** in this standard version. + +```json +{ + "catenaXId" : "580d3adf-1981-44a0-a214-13d6ceed9379", + "partTypeInformation" : { + "partClassification" : [ + { + "classificationStandard": "GIN 20510-21513", + "classificationID": "1004716", + "classificationDescription": "Generic standard for classification of parts in the automotive industry." + }, + { + "classificationStandard": "OEM Part Classification 1022-102", + "classificationID": "Exterior mirror", + "classificationDescription": "OEM standard for classification of parts." + } + ], + "manufacturerPartId" : "123-0.740-3434-A", + "nameAtManufacturer" : "Mirror left" + }, + "partSitesInformationAsPlanned" : [ + { + "functionValidUntil" : "2024-01-29T12:00:00.123+02:00", + "catenaXsiteId" : "BPNS1234567890ZZ", + "function" : "production", + "functionValidFrom" : "2024-01-29T12:00:00.123+02:00" + } + ] +} +``` + +### 3.2 ASPECT MODEL "SingleLevelBomAsPlanned" + +#### 3.2.1 INTRODUCTION + +The aspect SingleLevelBomAsPlanned provides information on the child parts (one structural level down) from which a given object is to be assembled or produced. It describes the relationship of parts/materials in a planned stage. It does not hold serial number or batch specific information, but supports navigation through the potential supply chains (top-down) for a given material/part number. + +This model was modelled **conform to** the Catena-X standard **CX-0045 Aspect Model Data Chain Template**. + +**Note:** The Aspect model SingleLevelBomAsPlanned **v3.0.0** is **mandatory**. Versions higher than that are **optional**, but might become mandatory in future releases of this standard. For the changelog of the aspect model, [see here](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_bom_as_planned/RELEASE_NOTES.md). + +#### 3.2.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#62-non-normative-references). + +The aspect model SingleLevelBomAsPlanned v3.0.0 is written in SAMM 2.1.0 as a modeling language conformant to *CX-0003 SAMM Semantic Aspect Meta Model* as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003. + +#### 3.2.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group Industry Core. This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons[^2]. + +The license information is available in GitHub. In case of doubt the license, copyright and authors information in github overwrites the information in this specification document. + +#### 3.2.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model SingleLevelBomAsPlanned **v3.0.0** has the unique identifier: + +```text +urn:samm:io.catenax.single_level_bom_as_planned:3.0.0#SingleLevelBomAsPlanned +``` + +#### 3.2.5 FORMATS OF SEMANTIC MODEL + +##### 3.2.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. This can be viewed by following link: + +- [SingleLevelBomAsPlanned (v3.0.0)](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_bom_as_planned/3.0.0/SingleLevelBomAsPlanned.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework[^3] is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.2.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.2.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a submodel template specification conformant to [SMT](#62-non-normative-references). + +**Note:** As soon as the specification v3.0 of the Asset Administration Shell specification is available an update will be provided. + +#### 3.2.6 EXAMPLE DATA + +Example JSON payload: Submodel "SingleLevelBomAsPlanned" v3.0.0 for a [PartTypeInformation](#31-aspect-model-parttypeinformation) that is **mandatory** in this standard version. + +```json +{ + "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d", + "childItems": [ + { + "validityPeriod": { + "validFrom": "2023-03-21T08:17:29.187+01:00", + "validTo": "2024-07-01T16:10:00.000+01:00" + }, + "catenaXId": "urn:uuid:055c1478-0395-47m8-94de-7cf802c5724a", + "quantity": { + "value": 20, + "unit": "unit:piece" + }, + "businessPartner": "BPNL50096894aNXY", + "createdOn": "2022-02-03", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + } + ] +} +``` + +### 3.3 ASPECT MODEL "SingleLevelUsageAsPlanned" + +#### 3.3.1 INTRODUCTION + +The "Industry Core: Part Type" aims on planned product genealogy information throughout the supply chain. Therefore it is required to link a planned part with its predecessor items and its successor items. SingleLevelUsageAsPlanned is the submodel to build a successor linkage between the digital twins. It contains the customers and the unique identifiers of the successor items (usage) of a planned product and therefore allows bottom-up navigation through the supply chain by Catena-X identifiers. + +More specific, the aspect provides information on the customers and the parent items (one structural level up) that will be produced or assembled from the given object. It creates the relationship of one part type in the asPlanned lifecycle phase with its parent items by referencing the part type digital twin of such item. + +To be able to reference the unique identifiers of the successor items (usage) the data provider of this aspect model has to rely on their customer to provide them the correct information of that item. If the data provider does not have that information they are unable to provide the successor item but only the customer. + +This model was modelled **conform to** the Catena-X standard **CX-0045 Aspect Model Data Chain Template**. + +**Note:** The Aspect model SingleLevelUsageAsPlanned **v2.0.0** is **mandatory**. Versions higher than that are **optional**, but might become mandatory in future releases of this standard. For the changelog of the aspect model, [see here](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_usage_as_planned/RELEASE_NOTES.md). + +#### 3.3.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#62-non-normative-references). + +The aspect model SingleLevelUsageAsPlanned v2.0.0 is written in SAMM 2.1.0 as a modeling language conformant to *CX-0003 SAMM Semantic Aspect Meta Model* as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003. + +#### 3.3.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group Industry Core. This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons[^2]. + +The license information is available in GitHub. In case of doubt the license, copyright and authors information in github overwrites the information in this specification document. + +#### 3.3.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model SingleLevelUsageAsPlanned **v2.0.0** has the unique identifier: + +```text +urn:samm:io.catenax.single_level_usage_as_planned:2.0.0#SingleLevelUsageAsPlanned +``` + +#### 3.3.5 FORMATS OF SEMANTIC MODEL + +##### 3.3.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. This can be viewed by following link: + +- [SingleLevelUsageAsPlanned (v2.0.0)](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_usage_as_planned/2.0.0/SingleLevelUsageAsPlanned.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework[^3] is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.3.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.3.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a submodel template specification conformant to [SMT](#62-non-normative-references). + +**Note:** As soon as the specification v3.0 of the Asset Administration Shell specification is available and update will be provided. + +#### 3.3.6 EXAMPLE DATA + +Example JSON payload: Submodel "SingleLevelUsageAsPlanned" v2.0.0 for a [PartTypeInformation](#31-aspect-model-parttypeinformation) that is **mandatory** in this standard version. + +```json +{ + "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d", + "parentItems": [ + { + "validityPeriod": { + "validFrom": "2023-03-21T08:17:29.187+01:00", + "validTo": "2024-07-01T16:10:00.000+01:00" + }, + "catenaXId": "urn:uuid:055c1478-0395-47m8-94de-7cf802c5724a", + "quantity": { + "value": 20, + "unit": "unit:piece" + }, + "businessPartner": "BPNL50096894aNXY", + "createdOn": "2022-02-03", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + } + ], + "customers": [ + "BPNL50096894aNXY" + ] +} +``` + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +### 4.1 UNIQUE ID PUSH NOTIFICATION API + +Unique ID Push notifications provide the possibility to push specific information to a business partner in the value chain (one level up). This can help to provide faster information to reduce necessary information collection activities. + +The Unique ID Push Notification API **MAY** be used to push the information “Connect to Parent” to a business partner. +The information “Connect to Parent” **MUST NOT** be provided in any other way than with the Unique ID Push Notification API. + +**Connect to Parent** + +Unique ID Push notifications of type "connect-to-parent" are a way for a manufacturer to notify a customer as soon as possible when a new digital twin for a part is available. + +The sender of the notification is the supplier of a part item and the receiver of the notification is the customer of that part item. The Unique ID of that part is sent in the notification. + +Connect to Parent notifications **MAY BE** applied to Digital Twins for part instances and for part types. + +#### 4.1.1 PRECONDITIONS AND DEPENDENCIES + +Application providers **MUST** prove their conformity by providing: An openAPI specification of the endpoints described. Examples of the data asset and contract definition structure in their Tractus-X EDC or any other CX-0018 compliant connector. + +The Unique ID Push Notification API **MUST** be published towards the network using a Data Asset/Contract Definition in terms of the IDSA Protocol as described by the reference implementation CX-0018. + +The Eclipse Dataspace Connector as a reference implementation **SHOULD BE** used and is referenced in this document. Other connectors fulfilling the same standards towards Catena-X **MAY** be leveraged as well. + +It is of importance to mention, that there **MUST** be an API available behind each of the data offers described in the dataspace connector, which works according to the openAPI specifications description. Nevertheless, the APIs are **OPTIONAL** to follow the same structure, as there could even be APIs taking over the job of several of the endpoints mentioned. + +The dataspace connector **SHOULD** act as a reverse proxy towards those APIs, as it holds the Data Offers linked to the respective implemented endpoints. + +#### 4.1.2 API SPECIFICATION + +##### 4.1.2.1 API ENDPOINTS + +The Unique ID Push Notification API **MUST** be implemented as specified in the openAPI documentation as stated here: [openAPI](https://github.com/catenax-eV/product-standardization-prod/blob/main/standards/CX-0126-IndustryCorePartType/2.0.0/src/unique-id-push-2-0-0.yaml). + +To enable compatibility with future versions, additional, unknown attributes in the API can be ignored. + +The Unique ID Push Notification API **MUST** implement one endpoint: + +```text +POST/uniqueidpush/connect-to-parent +``` + +In fact, it is **OPTIONAL** to implement the endpoint paths exactly as described above. The reason is that those endpoints are not called from any supply chain partner directly. Rather, they are called from the Tractus-X EDC as part of data assets. In that sense, it is just important to implement endpoints that can process the defined request body and respond with the HTTP status codes and - if required - reply with the defined response body. + +The data assets will act similar to a reverse proxy for the notification endpoints, therefore rather the data assets are of significance, which **SHOULD** be exposed towards Catena-X through the Data Offer Catalogues in the Tractus-X EDC or any other CX-0018 compatible connector + +##### 4.1.2.2 AVAILABLE DATA TYPES + +The notification API **MUST** use JSON as the payload transported via HTTP. + +##### 4.1.2.3 API RESOURCES & ENDPOINTS + +The HTTP POST endpoints introduced in this standard **MUST** be called via Data Space Protocol. The sending and receiving of notifications **MUST** be built on the basis of HTTP POST endpoints. + +#### 4.1.3 DATA ASSET STRUCTURE + +##### DATA ASSET FOR UNIQUE ID PUSH NOTIFICATION RECEIVE ENDPOINT + +When using the Tractus-X EDC or any other CX-0018 conformant connector, the following asset **MUST** be registered. Other connectors implementing the CX-0018 standard require a similar data asset with the same structure and provisioning towards Catena-X. + +The following properties must be set for this asset: + +```json +{ + "@context": { + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@id": "{{ _.assetId }}", + "properties": { + "dct:type": { "@id": "cx-taxo:UniqueIdPushConnectToParentNotification" }, + "cx-common:version": "2.0" + } +} + ``` + +Properties "dct:type" and "cx-common:version" are used to classify the asset and are explained in the [Digital Twin KIT](https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/Specification%20Digital%20Twin%20KIT#registration-at-edc) in more detail. + +#### 4.1.4 VERSIONING + +The API version described in this standard document **MUST** be published in the property https://w3id.org/catenax/ontology/common#version as version 2.0 in dcat:Dataset (http://www.w3.org/ns/dcat#). + +## 5 PROCESSES + +> *This section is normative* + +There is no prcoess defintion in this standard version available. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normative* + +- CX-0001 EDC DISCOVERY API 1.0.2 +- CX-0002 Digital Twins in Catena-X 2.2.0 +- CX-0003 SAMM Aspect Meta Model 1.1.0 +- CX-0018 Dataspace Connectivity 3.0.0 +- CX-0045 Data Chain Template 1.3.0 +- CX-0053 BPN Discovery Services 1.1.0 + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf + +[^1]: https://github.com/eclipse-tractusx/sldt-semantic-models + +[^2]: https://creativecommons.org/licenses/by/4.0/legalcode + +[^3]: https://github.com/eclipse-esmf/esmf-sdk + +[^4]: [CX Operating Model](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf) + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +[Item Relationship Service](https://github.com/eclipse-tractusx/item-relationship-service) + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +This section is empty. + +### TABLES + +> *This section is non-normative* + +This section is empty. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0127-IndustryCorePartInstance/CX-0127-IndustryCorePartInstance.md b/docs/standards/CX-0127-IndustryCorePartInstance/CX-0127-IndustryCorePartInstance.md new file mode 100644 index 000000000..4e2922895 --- /dev/null +++ b/docs/standards/CX-0127-IndustryCorePartInstance/CX-0127-IndustryCorePartInstance.md @@ -0,0 +1,1133 @@ +# CX-0127 Industry Core: Part Instance 2.0.0 + +## ABSTRACT + +This standard describes the "Industry Core: Part Instance". It sets the foundation to describe, identify and find a component on an instance level and enables traversing across several levels in both directions to ensure the creation of data chains. The core makes it possible to configure enablement services for component-based data exchange. Other use cases are meant to build upon the foundation that is given by the industry core. + +## FOR WHOM IS THE STANDARD DESIGNED + +This standard is designed for everybody who wants to register, describe and use digital twins on part instance level. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +- New versions of aspect models in [Section 3](#3-aspect-models) + - SerialPart 3.0.0 (see link to changelog in section of the aspect model) + - Batch 3.0.0 (see link to changelog in section of the aspect model) + - JustInSequencePart 3.0.0 (see link to changelog in section of the aspect model) + - SingleLevelBomAsBuilt 3.0.0 (see link to changelog in section of the aspect model) +- Newly standardized aspect models in [Section 3](#3-aspect-models) + - SingleLevelUsageAsBuilt 3.0.0 (see link to changelog in section of the aspect model) +- Aspect model JustInSequencePart now **MUST** be provided when creating a digital twin for a Just-In-Seuqence-Part (was optional before) in [Section 2.1.2](#212-data-required) +- Changes in specificAssetIds of Digital Twins in [Section 2.1.4](#214-digital-twins-and-specific-asset-ids) + - Removed assetLifeCyclePhase + - DigitalTwinType is now mandatory (before it was optional) + - Added intrinsicId specifically for Digital Twins for serialized parts, batches and just-in-sequence-parts + - Removed partInstanceId from Digital Twins for batches and just-in-sequence-parts +- Added Unique ID Push Notification API in [Section 4.1](#41-unique-id-push-notification-api) as content of industry core +- New paragraph "Conventions for Use Case Policy in context data exchange" in [Section 2.1.3](#213-additional-requirements) +- Added notes for versioning in [Section 2.1.3](#213-additional-requirements) +- Deleted "Every certified business application relying on aspects models of this standard **MUST** be able to consume data conformant to the semantic models specified in this document." from [Section 3](#3-aspect-models) + +Note: This release (**24.05.**) contains **breaking changes**! + +## 1 INTRODUCTION + +This standard contains all information on the "Industry Core: Part Instance". The Industry Core is a shared foundation for use cases that utilize digital twins and aspect models in Catena-X. The "Industry Core: Part Instance" describes digital twins and aspect models that are used to represent identifiable instantiated parts, such as serial parts, just-in-sequence parts or batches, and describes those in the Catena-X network. Digital twins and aspect models are meant to be reused by other use cases as much as possible, in order to simplify data provisioning across different use cases. +The "Industry Core: Part Instance" provides the basis for the identification, description, findability of part instance digital twins in the Catena-X network and the connection of those twins to build data chains across the supply chain in both directions. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This document is targeting subsets of the following roles: + +- Data Provider / Consumer +- Business Application Provider +- Enablement Service Provider + +Note: Fulfilling a use-case standard by a data provider / consumer can be done in two ways: + +1. Purchase a certified app for the use-case. In this case the data provider / consumer does not need to proof conformity again and +2. Data Provisioning / Consumption without a certified app for the use-case. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +The aim of the "Industry Core: Part Instance" is to build the foundation to describe, identify and find a component on an instance level and enables traversing across the levels of the supply chain to ensure the creation of data chains and enable data driven use cases over all n-tier levels without compromising data sovereignty. This standard enables data and app providers to deliver solutions for building data chains for identifiable instantiated parts, such as serialized parts, vehicles, just-in-sequence parts and batches. This is achieved via the standardized creation of digital twins of those entities as well as the logical linking to their parent and child components (Bill of Material as built, Usage as Built). + +The "Industry Core: Part Instance" is not intended to include all information that may be needed in an use case. Instead, it allows the establishment of a value driven data chain and serves as a basis for further data driven use cases. +It enables data owners to provide necessary data with individual access rights and usage restrictions (access and usage policies) to ensure privacy and security. Additional information might be shared by utilizing the Asset Administration Shell through additional aspects or submodels. + +The "Industry Core: Part Instance" is supporting the availability of data of identifiable instantiated parts and the connection to their parent and child parts. It describes the concrete digital reflection of a produced vehicle, product or part and its provisioning towards Catena-X including Interoperability and Data Sovereignty standards and components by the participants willing to share such data. This standard also defines which components (e.g. Digital Twin Registry, CX-0018 compliant connector) must be used in order to be interoperable and sovereign in a data exchange as defined in Catena-X. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +In addition to all sections that are marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are also non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +All participants* and their solutions will need to proof, that they are conform with the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). +Please refer to: https://catena-x.net/en/catena-x-introduce-implement/certification for the process of conformity assessment and certification. + +The specific criteria described in this document are describing the usage of the central tools as well as common tools described in the linked standardization documents and therefore compliance should be checked with the tools provided for these components. + +The versions of the standardization documents valid for this standard are mentioned in sections where the [standalone standards](#211-list-of-standalone-standards), [normative references](#61-normative-references) and [non-normative references](#62-non-normative-references) are listed. The valid versions are not specifically mentioned in the body text. + +**Disclaimer: The operating model released by the Catena-X association will define the roadmap, content and scope for the certification process. This will include the roles, certification and further assessment procedures as well as the rollout phases.* + +### 1.4 EXAMPLES + +Examples for data models: See according subsection [3 Aspect Models](#3-aspect-models). + +Examples for APIs: See according subsection [4 Application Programming Interfaces](#4-application-programming-interfaces) + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +**Aspect Model**: +A formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect. +An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model. +Aspect models are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +**Batch**: +A batch is a quantity of (semi-) finished products or (raw) material +products that have been produced under the same circumstances (e.g., same +production location), as specified groups or amounts, within a certain +time frame. Every batch can differ in the number or amount of products. +Different batches can have varied specifications, e.g., different +colors, quality, etc. A batch is identified via a Batch ID. + +**Business Partner Number (BPN)**: +A BPN is the unique identifier of a partner within Catena-x. + +**Tractus-X Eclipse Dataspace Connector (Tractus-X EDC)**: +The Tractus-X EDC is a reference implementation for a connector conformant to CX-0018 currently acting as a de-facto standard and/or reference Implementation within Catena-X. When mentioning the Tractus-X EDC in this standard, any other CX-0018 conformant connector is also a valid option. + +**International Data Space (IDS)**: +International Data Space and its protocol for data exchange foresees a compliant connector handling contract negotiations before each data transfer and defines a general architecture for data exchange. + +**Just-in-sequence-part**: +Just-in-sequence is a delivery concept where parts are delivered to the production plant at a requested time in the exact order of installation, typically for a 1:1 dependency on the manufactured product. A just-in-sequence-part is a part for which this concept and order of delivery applies and which does not have a dedicated serial number (then it would be considered a serialized part). Examples for JIS-parts are seats and bumpers. + +**Part Instance**: A part instance is a physically produced instance (e.g. serialized part, batch, just-in-sequence-part) of a part type. + +**Part Type**: A part type is a generic (not physically produced) part on material- or catalog-level as a representation for a designed part. + +**Serialized part**: +Instance of a part, where the particular instance can be uniquely identified by means of a serial number, a similar identifier (e.g. VAN) or a combination of multiple identifiers (e.g. combination of manufacturer, date and number). + +**Vehicle Anonymised Number (VAN)**: +A number mapped 1:1 to VIN, but pseudonymized. + +**Vehicle Identification Number (VIN)**: +The VIN number is a 17-character code assigned by the manufacturer to every vehicle, providing specific information about its brand, model, year of manufacture, and other key features. It is a unique identifier that allows the vehicle to be easily tracked and identified throughout its lifespan. + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 "Data Provisioning Industry Core: Part Instance" + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +To participate in Data Provisioning for the "Industry Core: Part Instance", the following single standards **MUST** be fulfilled by all participants for which the standard is relevant: + +- CX-0002 Digital Twins in Catena-X 2.2.0 +- CX-0018 Dataspace Connectivity 3.0.0 + +#### 2.1.2 DATA REQUIRED + +A digital twin **MAY** be created for serialized part, just-in-sequence-part or batch of materials produced by the manufacturer. + +The digital twin **MUST** be provisioned via an Asset Administration Shell as per CX-0002 and registered in a decentral Digital Twin Registry of the data provider (or the decentral Digital Twin Registry host of the manufacturer) as described in CX-0002. + +The aspect model "SerialPart" **MUST** be linked to the Asset Administration Shell of a serialized part. + +The aspect model "JustInSequencePart" **MUST** be linked to the Asset Administration Shell of a just-in-sequence-part. + +The aspect model "Batch" **MUST** be linked to the Asset Administration Shell of a Batch. + +The aspect model "SingleLevelBomAsBuilt" **MAY** be linked to the Asset Administration Shell of each part and each batch holding the information on relationship of serialized items and batches. Information on the Bill of Material of those parts and batches **MUST NOT** be provided in any other way than with the aspect model "SingleLevelBomAsBuilt". + +The aspect model "SingleLevelUsageAsBuilt" **MAY** be linked to the Asset Administration Shell of each part and each batch holding the information on usage of this part or batch in serialized items or products in general. Information on the usage of those parts and batches **MUST NOT** be provided in any other way than with the aspect model "SingleLevelUsageAsBuilt". + +The submodel data **MUST** be transferred using the IDS Protocol as described in CX-0018. +The Tractus-X EDC as a reference implementation is **RECOMMENDED** to be used as a connector conformant to CX-0018. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +As the IDS protocol is being used, data **MUST NOT** be transferred before a corresponding contract negotiation has been successfully passed by the participants of the data exchange and a valid contract is present as described in CX-0018. +The required data offers **MUST** be discoverable through the decentral Digital Twin Registry as submodel endpoints. + +#### Conventions for Use Case Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +##### Additional Details regarding Access Policies + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +##### Additional Details regarding Usage Policies + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +##### Versioning + +The Aspect Models that are deployed as Digital Twins **MUST** be published in [dcat:Dataset](http://www.w3.org/ns/dcat#) in the property that holds the full URN of the Aspect Model https://admin-shell.io/aas/3/0/HasSemantics/semanticId. Versions are explicitly contained in the URN. +The API versions **MUST** be published in the property https://w3id.org/catenax/ontology/common#version as version X.Y in [dcat:Dataset](http://www.w3.org/ns/dcat#). +Note: Data Assets differentiated only by major version **MUST** be offered in parallel. The current standard and API versions mark the start of Life Cycle Management in Catena-X operations. Previous versions are dismissed. + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +The asset's globalAssetId **MUST** be equal to the unique id used in Catena-X. + +The following specific asset IDs not marked as optional **MUST** be available when registering a digital twin or when adding the above mentioned submodels to an existing twin for a part instance in order to allow discovery (see CX-0002 for additional information). The specific asset IDs marked as optional **MAY** be used in addition. + +The following conventions for specific Asset IDs apply to all digital twins: + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Key Availability Description Type
    manufacturerId Mandatory The Business Partner Number (BPNL) of the manufacturer of the part. BPNL
    manufacturerPartId Mandatory The ID of the type/catalog part from the ***manufacturer***. String
    customerPartId Optional The ID of the type/catalog part from the ***customer***.

    The main reason why this property is optional is that it cannot be guaranteed that every manufacturer knows the customerPartId for their parts. If known, it is ***recommended*** to always add the customerPartId for easier lookup.
    		 String
    digitalTwinType Mandatory The types of the digital twin:
    • "PartInstance" for serialized parts, batches, and JIS parts
    • "PartType" for catalog parts
    DigitalTwinType was added to allow data consumers to search for all digital twins of a particular type, e.g, only for catalog parts by using `digitalTwinType="PartType"` as filter. Without this filter, a search for a particular manufacturer part ID would not only return the digital twin of the catalog part, but also all digital twins of instances of this catalog part, i.e., of the corresponding serial parts.    		 String
    + +**For serialized parts, additionally the following conventions apply:** + +| Key | Availability | Description | Type | +| :------------- | :----------- | :------------------------------------------------------------------------------------------- | :----- | +| partInstanceId | Mandatory | The serial number of the part from the manufacturer. | String | +| intrinsicId | Mandatory | The serial number of the part from the manufacturer. | String | +| van | Optional | **Only for vehicles:** The pseudonymized vehicle identification number (VIN) of the vehicle. | String | + +**For batches, additionally the following conventions apply:** + +| Key | Availability | Description | Type | +| :------------- | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | +| batchId | Mandatory | The number of the batch from the manufacturer. | String | +| intrinsicId | Mandatory | Also the number of the batch from the manufacturer.

    Currently, we also use the batch number as intrinsicId. This makes looking up digital twins for serialized parts and batches easier as a data consumer only has to specify the intrinsicId no matter if they are looking up a serialized part or a batch. Otherwise, the data consumer would need to know for what type of digital twin it is looking for or it would have to look for both until a match is found. | String | + +**For just-in-sequence-parts, additionally the following conventions apply:** + +| Key | Availability | Description | Type | +| :---------------- | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | +| parentOrderNumber | Optional | A number identifying the just-in-sequence- part's destination parent part. The parent part is typically known upfront to the supplier for just-in-sequence parts. | String | +| jisNumber | Mandatory | A number that is used to identify the call-off that can be assumed unique within the specific just-in-sequence process. This is typically not the sequence number, but the call-off number. | String | +| jisCallDate | Optional | The date of the just-in-sequence call-off as stated on the call-off document itself.
    The value must be compliant to ISO 8601: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` or `YYYY-MM-DDThh:mm:ss±hh:mm` | Date | +| intrinsicId | Mandatory | A composition of `jisNumber`, `parentOrderNumber` (if available), `jisCallDate` (if available). This information is typically known upfront to the supplier `jisNumber`, `partOrderNumber` and `jisCallDate` for just-in-sequence parts. | String | + +A digital twin is required for each single instance of a serialized part, just-in-sequence-part or vehicle and each batch to be traced. + +##### Authorization: Visbility of Specific Asset IDs in the DTR + +To enforce a strict need-to-know (and prevent data from being exposed to non-authorized parties), the visibility of entries in the attribute `specificAssetIds` https://admin-shell.io/aas/3/0/AssetInformation/specificAssetIds must be protected, i.e.,their visibility must be restricted to only the manufacturer of the part (which is represented by the digital twin) and the customers of the part. For that, the attribute `externalSubjectIds` (https://admin-shell.io/aas/3/0/SpecificAssetId/externalSubjectId) must be used. For more information on the semantics of the mentioned properties, see AAS Pt. 1. For more information on the use of Digital Twins in Catena-X, see CX - 0002. + +## 3 ASPECT MODELS + +> *This section is normative* + +Relevant semantic models of this standard are: + +- SerialPart +- Batch +- JustInSequencePart +- SingleLevelBomAsBuilt +- SingleLevelUsageAsBuilt + +Semantic models **MAY** be used individually or together. + +Semantic models **MUST** be made available in the central Semantic Hub. + +Data consumers and data provider **MUST** comply with the license of the semantic models. + +The submodel data **MUST** be requested and exchanged via a CX-0018 and CX-0002 compliant connector (e.g. Ecplise Dataspace Connector). + +Data providers **MUST** provide data as part of a digital twin of the asset for serialized parts conformant to CX – 0002 DIGITAL TWINS IN CATENA-X. + +The JSON Payloads of data providers **MUST** be conformant to the JSON Schemas as specified in this document. + +The unique identifier of the semantic model specified in this document **MUST** be used by the data provider to define the semantics of the data being transferred. + +### 3.1 ASPECT MODEL "SerialPart" + +#### 3.1.1 INTRODUCTION + +The semantic model SerialPart describes a submodel for a digital twin of a serialised part providing essential information about this part. A serialized part is an instance of a part, where the particular instance can be uniquely identified by means of a serial number, a similar identifier (e.g. VAN) or a combination of multiple identifiers (e.g. combination of manufacturer, date and number). +More specific, the model links local identifiers like manufacturerPartId, customerPartId and other data like manufacturing information and part type information to the actual catenaXId from Catena-X, which is a UUIDv4. +This allows decoupling of the network identifiers from the actual business process. +By accessing this aspect you can link a physical part to its representation within Catena-X. + +Note: The Aspect model SerialPart **v3.0.0** is **mandatory**. Versions higher than that are **optional**, but might become mandatory in future releases of this standard. + +For the changelog of the aspect model, [see here](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.serial_part/RELEASE_NOTES.md). + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#62-non-normative-references). + +The aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.1.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group +Industry Core. This Catena-X data model is made available under the terms +of the Creative Commons Attribution 4.0 International (CC-BY-4.0) +license, which is available at Creative Commons[^2]. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +SerialPart **v3.0.0** (mandatory) + +```text +urn:samm:io.catenax.serial_part:3.0.0#SerialPart +``` + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. These can be viewed by following links: + +SerialPart **v3.0.0** (mandatory) + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.serial_part/3.0.0/SerialPart.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework[^3] is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)]. + +#### 3.1.6 EXAMPLE DATA + +Example JSON payload: Submodel **"SerialPart" v3.0.0 for a vehicle** + +```json +{ + "localIdentifiers": [ + { + "key": "manufacturerId", + "value": "BPNL7588787849VQ" + }, + { + "key": "manufacturerPartId", + "value": "95657362-83" + }, + { + "key": "partInstanceId", + "value": "OEM-A-F8LM95T92WJ9KNDD3HA5P" + }, + { + "key": "van", + "value": "OEM-A-F8LM95T92WJ9KNDD3HA5P" + } + ], + "manufacturingInformation": { + "date": "2022-02-04T14:48:54", + "country": "DEU", + "sites": [ + { + "catenaXsiteId": "BPNS1234567890ZZ", + "function": "production" + } + ] + }, + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "partTypeInformation": { + "manufacturerPartId": "95657362-83", + "nameAtManufacturer": "Vehicle Model A", + "partClassification": [ + { + "classificationStandard": "GIN 20510-21513", + "classificationID": "1004712", + "classificationDescription": "Generic standard for classification of parts in the automotive industry." + }, + { + "classificationStandard": "OEM Part Classification 1022-102", + "classificationID": "Electric vehicle", + "classificationDescription": "OEM standard for classification of parts." + } + ], + } +} +``` + +Example JSON payload: Submodel **"SerialPart" v3.0.0 for a Serialized Part (Non-Vehicle)** + +```json +{ + "localIdentifiers": [ + { + "key": "manufacturerId", + "value": "BPNL7588787849VQ" + }, + { + "key": "manufacturerPartId", + "value": "95657362-83" + }, + { + "key": "partInstanceId", + "value": "NO-574868639429552535768526" + } + ], + "manufacturingInformation": { + "date": "2022-02-04T14:48:54", + "country": "DEU", + "sites": [ + { + "catenaXsiteId": "BPNS1234567890ZZ", + "function": "production" + } + ] + }, + "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", + "partTypeInformation": { + "manufacturerPartId": "95657362-83", + "customerPartId": "798-515297795-A", + "nameAtManufacturer": "High Voltage Battery", + "nameAtCustomer": "High Voltage Battery", + "partClassification": [ + { + "classificationStandard": "GIN 20510-21513", + "classificationID": "1004713", + "classificationDescription": "Generic standard for classification of parts in the automotive industry." + }, + { + "classificationStandard": "OEM Part Classification 1022-102", + "classificationID": "Traction Battery", + "classificationDescription": "OEM standard for classification of parts." + } + ], + } +} +``` + +### 3.2 ASPECT MODEL "Batch" + +#### 3.2.1 INTRODUCTION + +A batch is a quantity of (semi-) finished products or (raw) material +product that have been produced under the same circumstances (e.g., same +production location), as specified groups or amounts, within a certain +time frame. Every batch can differ in the number or amount of products. +Different batches can have varied specifications, e.g., different +colors, quality, etc. A batch is identified via a Batch ID. + +This submodel template or aspect model is required to identify a batch +of materials within Catena-X. + +It links local identifiers like manufacturerPartId and batchId to +the actual Catena-X ID. + +This allows decoupling of the Catena-X identifiers from the actual +business process. + +By accessing this aspect you can link a physical batch of parts to its +representation within in Catena-X. + +Note: The Aspect model Batch **v3.0.0** is **mandatory**. Versions higher than that are **optional**, but might become mandatory in future releases of this standard. + +For the changelog of the aspect model, [see here](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.batch/RELEASE_NOTES.md). + +#### 3.2.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#62-non-normative-references). + +The aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.2.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group +Industry Core. This Catena-X data model is made available under the terms +of the Creative Commons Attribution 4.0 International (CC-BY-4.0) +license, which is available at Creative Commons[^2]. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.2.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier +Batch **v3.0.0** (mandatory) + +```text +urn:samm:io.catenax.batch:3.0.0#Batch +``` + +#### 3.2.5 FORMATS OF SEMANTIC MODEL + +##### 3.2.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is +the master for generating additional file formats and serializations. These can be viewed by following links: + +Batch **v3.0.0** (mandatory) + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.batch/3.0.0/Batch.ttl + +##### 3.2.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.2.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)]. + +#### 3.2.6 EXAMPLE DATA + +Example JSON payload: Submodel **"Batch" v3.0.0** + +```json +{ + "localIdentifiers": [ + { + "value": "BID12345678", + "key": "batchId" + }, + { + "value": "123-0.740-3434-A", + "key": "manufacturerPartId" + }, + ], + "manufacturingInformation": { + "date": "2022-02-04T14:48:54", + "country": "HUR", + "sites": [ + { + "catenaXsiteId": "BPNS1234567890ZZ", + "function": "production" + } + ] + }, + "catenaXId": "580d3adf-1981-44a0-a214-13d6ceed9379", + "partTypeInformation": { + "partClassification": [ + { + "classificationStandard": "GIN 20510-21513", + "classificationID": "1004714", + "classificationDescription": "Generic standard for classification of parts in the automotive industry." + }, + { + "classificationStandard": "OEM Part Classification 1022-102", + "classificationID": "Two-component adhesive", + "classificationDescription": "OEM standard for classification of parts." + } + ], + "manufacturerPartId": "123-0.740-3434-A", + "nameAtManufacturer": "PA66-GF30" + } +} +``` + +### 3.3 ASPECT MODEL "JustInSequencePart" + +#### 3.3.1 INTRODUCTION + +This submodel template or aspect model is required to identify a just-in-sequence-part within Catena-X (that do not have a dedicated serial number). +It links local identifiers like manufacturerPartId, jisNumber and jisCallDate to +the actual Catena-X ID. +This allows decoupling of the Catena-X identifiers from the actual +business process. +By accessing this aspect you can link a physical just-in-sequence-part to its +representation within in Catena-X. + +For just-in-sequence-parts with an existing serial number, the aspect model SerialPart is applied, not JustInSequencePart. + +Note: The Aspect model JustInSequencePart **v3.0.0** is **mandatory**. Versions higher than that are **optional**, but might become mandatory in future releases of this standard. + +For the changelog of the aspect model, [see here](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.just_in_sequence_part/RELEASE_NOTES.md). + +#### 3.3.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#62-non-normative-references). + +The aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.3.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group +Industry Core. This Catena-X data model is made available under the terms +of the Creative Commons Attribution 4.0 International (CC-BY-4.0) +license, which is available at Creative Commons[^2]. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.3.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +JustInSequencePart **v3.0.0** (mandatory) + +```text +urn:samm:io.catenax.just_in_sequence_part:3.0.0#JustInSequencePart +``` + +#### 3.3.5 FORMATS OF SEMANTIC MODEL + +##### 3.3.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is +the master for generating additional file formats and serializations. These can be viewed by following links: + +JustInSequencePart **v3.0.0** (mandatory) + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.just_in_sequence_part/3.0.0/JustInSequencePart.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework[^3] is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.3.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.3.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)]. + +#### 3.3.6 EXAMPLE DATA + +Example JSON payload: Submodel **"JustInSequencePart" v3.0.0** + +```json +{ + "localIdentifiers": [ + { + "key": "manufacturerId", + "value": "BPNL7588787849VQ" + }, + { + "key": "jisNumber", + "value": "894651684" + }, + { + "key": "parentOrderNumber", + "value": "OEM-A-F8LM95T92WJ9KNDD3HA5P" + }, + { + "key": "manufacturerPartId", + "value": "84816168424" + }, + { + "key": "nameAtManufacturer", + "value": "Black Leather Front Row Seat for Vehicle Model B" + }, + { + "key": "jisCallDate", + "value": "2022-01-24T09:13:34" + } + ], + "manufacturingInformation": { + "date": "2022-02-04T14:48:54", + "country": "DEU", + "sites": [ + { + "catenaXsiteId": "BPNS1234567890ZZ", + "function": "production" + } + ] + }, + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "partTypeInformation": { + "partClassification": [ + { + "classificationStandard": "GIN 20510-21513", + "classificationID": "1004715", + "classificationDescription": "Generic standard for classification of parts in the automotive industry." + }, + { + "classificationStandard": "OEM Part Classification 1022-102", + "classificationID": "Front row seat", + "classificationDescription": "OEM standard for classification of parts." + } + ], + "manufacturerPartId": "84816168424", + "nameAtManufacturer": "Black Leather Front Row Seat for Vehicle Model B", + } +} +``` + +### 3.4 ASPECT MODEL "SingleLevelBomAsBuilt" + +#### 3.4.1 INTRODUCTION + +The "Industry Core: Part Instance" aims on building product genealogy information throughout +the supply chain. Therefore it is required to link a produced part with +its predecessor and its successor items. +SingleLevelBoMAsBuilt is the submodel to build such a predecessor linkage between the digital twins. It contains the unique identifiers of the predecessor items of a produced or assembled part and therefore +allows top-down navigation through the supply chain by Catena-X identifiers. + +More specific, the aspect provides information on the child +items (one structural level down) from which the given object is +assembled. In first priority, it creates the relationship of one part instance in the asBuilt lifecycle phase with its child items by referencing the part instance digital twin of such item. However, when no part instance digital twin of the child item exists to reference, it is in a second priority possible to reference the part type twin of the child item instead. + +Because of gap of information in the production, it is sometimes not possible to identify the single correct digital twin to reference, but just a subset of potential twins. Then all potential alternative twins may be referenced. This will be marked by setting the property "hasAlternatives" true. If the exact digital twin is known, regardless of if it is a part type or part instance, just this one will be referenced and "hasAlternative" will be false. + +This model was modelled conform to the Catena-X standard CX-0045 Aspect Model Data Chain Template. + +Note: The Aspect model SingleLevelBomAsBuilt **v3.0.0** is **mandatory**. Versions higher than that are **optional**, but might become mandatory in future releases of this standard. + +For the changelog of the aspect model, [see here](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_bom_as_built/RELEASE_NOTES.md). + +#### 3.4.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#62-non-normative-references). + +The aspect model SingleLevelBomAsBuilt is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 +as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.4.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group +Industry Core. This Catena-X data model is made available under the terms +of the Creative Commons Attribution 4.0 International (CC-BY-4.0) +license, which is available at Creative Commons[^2]. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.4.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +SingleLevelBomAsBuilt **v3.0.0** (mandatory) + +```text +urn:samm:io.catenax.single_level_bom_as_built:3.0.0#SingleLevelBomAsBuilt +``` + +#### 3.4.5 FORMATS OF SEMANTIC MODEL + +##### 3.4.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is +the master for generating additional file formats and serializations. These can be viewed by following links: + +SingleLevelBomAsBuilt **v3.0.0** (mandatory) + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_bom_as_built/3.0.0/SingleLevelBomAsBuilt.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework[^3] is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.4.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.4.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)]. + +#### 3.4.6 EXAMPLE DATA + +Example JSON payload: Submodel **"SingleLevelBomAsBuilt" v3.0.0 for a SerialPart** + +```json +{ + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "childItems": [ + { + "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", + "quantity": { + "value": 1.0, + "unit": "unit:piece" + }, + "hasAlternatives": false, + "createdOn": "2022-02-03", + "businessPartner": "BPNL50096894aNXY", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + } + ] +} +``` + +Example JSON payload: Submodel **"SingleLevelBomAsBuilt" v3.0.0 for a Batch** + +```json +{ + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "childItems": [ + { + "catenaXId": "urn:uuid:d60b99b0-f269-42f5-94d0-64fe0946ed04", + "quantity": { + "value": 5.0, + "unit": "unit:kilogram" + }, + "hasAlternatives": false, + "createdOn": "2022-02-03", + "businessPartner": "BPNL50096894aNXY", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + } + ] +} +``` + +### 3.5 ASPECT MODEL "SingleLevelUsageAsBuilt" + +#### 3.5.1 INTRODUCTION + +The "Industry Core: Part Instance" aims on building product genealogy information throughout the supply +chain. Therefore it is required to link a produced part with its predecessor items and its successor items. +SingleLevelUsageAsBuilt is the submodel to build a successor linkage between the digital twins. It contains the +customers and the unique identifiers of the successor items (usage) of a produced or assembled product and +therefore allows bottom-up navigation through the supply chain by Catena-X identifiers. + +More specific, the aspect provides information on the customers and the parent items (one structural level up) that are produced or assembled from the given object. It creates the relationship of one part instance in the asBuilt lifecycle phase with its parent items by referencing the part instance digital twin of such item. In analogy to SingleLevelBomAsBuilt it is possible that a parent item cannot be specified at instance level and therefore no part instance digital twin of that item exists to be referenced. In that case, in contrast to SingleLevelBomAsBuilt, even if it would be possible to reference a part type twin of the parent part instead, no reference will be made. + +Because of gaps of information in the production, it is sometimes not possible to identify the single correct +digital twin to reference, but just a subset of potential twins that the item has been assembled into. Then from all potential alternative twins a reference can be done. To indicate that there is more than one parent item referenced as potential alternatives, the property "IsOnlyPotentialParent" will be set true for those references. If the exact digital twin of the parent part is known, the property "IsOnlyPotentialParent” will be set false. + +To be able to reference the unique identifiers of the successor items (usage) the data provider of this aspect model has to rely on their customer to provide them the correct information of that item. If the data provider does not have that information they are unable to provide the sucessor item but +only the customer. + +This model was modelled conform to the Catena-X standard CX-0045 Aspect Model Data Chain Template. + +Note: The Aspect model SingleLevelUsageAsBuilt **v3.0.0** is **mandatory**. Versions higher than that are **optional**, but might become mandatory in future releases of this standard. + +For the changelog of the aspect model, [see here](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_usage_as_built/RELEASE_NOTES.md). + +#### 3.5.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#62-non-normative-references). + +The aspect model SingleLevelUsageAsBuilt is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 +as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +#### 3.5.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group +Industry Core. This Catena-X data model is made available under the terms +of the Creative Commons Attribution 4.0 International (CC-BY-4.0) +license, which is available at Creative Commons[^2]. + +The license information is available in github. + +In case of doubt the license, copyright and authors information in +github overwrites the information in this specification document. + +#### 3.5.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +SingleLevelUsageAsBuilt **v3.0.0** (mandatory) + +```text +urn:samm:io.catenax.single_level_usage_as_built:3.0.0#SingleLevelUsageAsBuilt +``` + +#### 3.5.5 FORMATS OF SEMANTIC MODEL + +##### 3.5.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is +the master for generating additional file formats and serializations. These can be viewed by following links: + +SingleLevelUsageAsBuilt **v3.0.0** (mandatory) + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_usage_as_built/3.0.0/SingleLevelUsageAsBuilt.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework[^3] is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.5.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.5.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)]. + +#### 3.5.6 EXAMPLE DATA + +Example JSON payload: Submodel **"SingleLevelUsageAsBuilt" v3.0.0 for a SerialPart** + +```json +{ + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "parentItems": [ + { + "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d", + "isOnlyPotentialParent": false, + "quantity": { + "value": 1.0, + "unit": "unit:piece" + }, + "createdOn": "2022-02-03", + "businessPartner": "BPNL50096894aNXY", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + } + ], + "customers": [ + "BPNL50096894aNXY" + ] +} +``` + +Example JSON payload: Submodel **"SingleLevelUsageAsBuilt" v3.0.0 for a Batch** + +```json +{ + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "parentItems": [ + { + "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d", + "isOnlyPotentialParent": false, + "quantity": { + "value": 25.0, + "unit": "unit:kilogram" + }, + "createdOn": "2022-02-03", + "businessPartner": "BPNL50096894aNXY", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + } + ], + "customers": [ + "BPNL50096894aNXY" + ] +} +``` + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +### 4.1 UNIQUE ID PUSH NOTIFICATION API + +Unique ID Push notifications provide the possibility to push specific information to a business partner in the value chain (one level up). This can help to provide faster information to reduce necessary information collection activities. + +The Unique ID Push Notification API **MAY** be used to push the information “Connect to Parent” to a business partner. +The information “Connect to Parent” **MUST NOT** be provided in any other way than with the +Unique ID Push Notification API. + +**Connect to Parent** + +Unique ID Push notifications of type "connect-to-parent" are a way for a manufacturer to notify a customer as soon as possible when a new digital twin for a part is available. + +The sender of the notification is the supplier of a part item and the receiver of the notification is the customer of that part item. The Unique ID of that part is sent in the notification. + +Connect to Parent notifications **MAY** be applied to Digital Twins for part instances and for part types. + +#### 4.1.1 PRECONDITIONS AND DEPENDENCIES + +Application providers **MUST** prove their conformity by providing: +An openAPI specification of the endpoints described. + +Examples of the data asset and contract definition structure in their Tractus-X EDC or any other CX-0018 compliant connector. + +The Unique ID Push Notification API **MUST** be published towards the network using a Data Asset/Contract Definition in terms of the IDSA Protocol as described by the reference implementation [CX-0018]. + +The Eclipse Dataspace Connector as a reference implementation **SHOULD BE** used and is referenced in this document. Other connectors fulfilling the same standards towards Catena-X **MAY** be leveraged as well. + +It is of importance to mention, that there **MUST** be an API available behind each of the data offers described in the dataspace connector, which works according to the openAPI specifications description. + +Nevertheless, the APIs are **OPTIONAL** to follow the same structure, as there could even be APIs taking over the job of several of the endpoints mentioned. + +The dataspace connector **SHOULD** act as a reverse proxy towards those APIs, as it holds the Data Offers linked to the respective implemented endpoints. + +#### 4.1.2 API SPECIFICATION + +##### 4.1.2.1 API-ENDPOINTS + +The Unique ID Push Notification API **MUST** be implemented as specified in the openAPI documentation as stated here: [openAPI](https://github.com/catenax-eV/product-standardization-prod/tree/main/standards/CX-0127-IndustryCorePartInstance/2.0.0/src/unique-id-push-2-0-0.yaml) + +To enable compatibility with future versions, additional, unknown attributes in the API can be ignored. + +The Unique ID Push Notification API **MUST** implement one endpoint: + +```text +POST/uniqueidpush/connect-to-parent +``` + +In fact, it is **OPTIONAL** to implement the endpoint paths exactly as described above. The reason is that those +endpoints are not called from any supply chain partner directly. Rather, they are called from the Tractus-X EDC as part of data assets. In that sense, it is just important to implement +endpoints that can process the defined request body and respond with the HTTP status codes and - if +required - reply with the defined response body. + +The data assets will act similar to a reverse proxy for the notification endpoints, therefore rather the +data assets are of significance, which **SHOULD** be exposed towards Catena-X through the Data Offer +Catalogues in the Tractus-X EDC or any other CX-0018 compatible connector. + +##### 4.1.2.2 AVAILABLE DATA TYPES + +The notification API **MUST** use JSON as the payload transported via HTTP. + +##### 4.1.2.3 API RESOURCES & ENDPOINTS + +The HTTP POST endpoints introduced in this standard **MUST** be called via Data Space Protocol. +The sending and receiving of notifications **MUST** be built on the basis of HTTP POST endpoints. + +#### 4.1.3 DATA ASSET STRUCTURE + +##### DATA ASSET FOR UNIQUE ID PUSH NOTIFICATION RECEIVE ENDPOINT + +When using the Tractus-X EDC or any other CX-0018 conformant connector, the following asset **MUST** be registered. Other connectors implementing the CX-0018 +standard require a similar data asset with the same structure and provisioning towards Catena-X. + +The following properties must be set for this asset: + +```json +{ + "@context": { + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@id": "{{ _.assetId }}", + "properties": { + "dct:type": { "@id": "cx-taxo:UniqueIdPushConnectToParentNotification" }, + "cx-common:version": "2.0" + } +} +``` + +Properties "dct:type" and "cx-common:version" are used to classify the asset and are explained in the [Digital Twin KIT](https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/Specification%20Digital%20Twin%20KIT#registration-at-edc) in more detail. + +#### 4.1.4 VERSIONING + +The API version described in this standard document **MUST** be published in the property https://w3id.org/catenax/ontology/common#version as version 2.0 in [dcat:Dataset](http://www.w3.org/ns/dcat#). + +## 5 PROCESSES + +> *This section is normative* + +There is no prcoess defintion in this standard version available. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normative* + +- CX-0001 EDC DISCOVERY API 1.0.2 +- CX-0002 Digital Twins in Catena–X 2.2.0 +- CX-0003 SAMM Aspect Meta Model 1.1.0 +- CX–0018 Dataspace Connectivity 3.0.0 +- CX-0045 Aspect Model Data Chain Template 1.3.0 +- CX-0053 BPN Discovery Services 1.1.0 + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +\[SMT\] How to create a submodel template specification. Guideline. +Download from: + +https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf + +[^1]: https://github.com/eclipse-tractusx/sldt-semantic-models + +[^2]: https://creativecommons.org/licenses/by/4.0/legalcode + +[^3]: https://github.com/eclipse-esmf/esmf-sdk + +[^4]: https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +[Item Relationship Service](https://github.com/eclipse-tractusx/item-relationship-service) + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +This section is empty. + +### TABLES + +> *This section is non-normative* + +This section is empty. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/CX-0128-DemandandCapacityManagementDataExchange.md b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/CX-0128-DemandandCapacityManagementDataExchange.md new file mode 100644 index 000000000..5f9dd259f --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/CX-0128-DemandandCapacityManagementDataExchange.md @@ -0,0 +1,2247 @@ +# CX-0128 - Demand and Capacity Management Data Exchange v2.0.0 + +## ABSTRACT + +> *This section and all its subsections are non-normative* + +The Catena-X **D**emand and **C**apacity **M**anagement (DCM) standard is designed for all members of the automotive supply chain. Its goal is to help these members **prevent or anticipate production issues** that can arise from fluctuations in demand or capacity planning. This standard is particularly relevant for mid- to long-term planning, covering periods up to 24 months into the future. **Effective collaboration between partners in a direct business relationship (also referred to as “one-up” and “one-down”) is a key element of success**. + +The Catena-X DCM standard is accessible to all supply chain participants, including suppliers and Original Equipment Manufacturers (OEMs), regardless of their size and position in the supply chain. It is particularly useful for those involved in **production and production planning**. The standard prioritizes parts and materials that are critical to manufacturing, aiming to create mutually beneficial outcomes for all parties involved and to **enhance the flexibility in meeting customer needs**. + +This standard offers an alternative to proprietary systems or manual processes that are often resource-intensive and prone to errors. It provides a **collaborative foundation for demand and capacity management within the automotive industry**, ensuring **compatibility** with existing systems and maintaining **data sovereignty** for all users. + +Recent global supply chain disruptions have highlighted the need for greater resilience. The automotive industry, with its complex and volatile environment, has multiple IT solutions and interfaces within a single company and across the supply chain. However, there is a lack of a unified process understanding among all partners. + +Demand and Capacity Management (DCM) involves the exchange of demand and capacity data between customers and suppliers within their direct business relationships. Customers communicate their anticipated material needs for specific timeframes and suppliers respond with their planned production capacities for those materials and timeframes. + +For successful DCM, companies must share a common understanding that enables the exchange of data across different partners and systems while respecting each partner's data sovereignty. + +This standard describes the data models, data exchange protocols and a core business logic for interpreting the data, ensuring a consistent approach for all DCM participants. + +Cross-company interactions and common business logic required for DCM are standardized in [Chapter 5](#5-processes), while the Application Programming Interfaces (APIs) are described in [Chapter 4](#4-application-programming-interfaces). The data models are presented in [Chapter 3](#3-aspect-models). + +## COMPARISON WITH PREVIOUS VERSIONS OF THIS STANDARD + +> *This section and all its subsections are non-normative* + +### Release 24.05 + +- Replaced `MaterialDemand` with `WeekBasedMaterialDemand` aspect model +- Added deactivation of `WeekBasedCapacityGroup` to [Section 4.2.2.2](#4222-data-exchange) +- Added deactivation of `WeekBasedMaterialDemand` to [Section 4.1.2.2](#4122-data-exchange) +- Added [Chapter 2.3](#23-additional-requirements) Additional Requirements +- Added [Chapter 5.10](#510-supply-chain-disruption-notifications) Supply Chain Disruption Notifications +- Added [Chapter 5.11](#511-demand-volatility-metrics) Demand Volatility Metrics +- Added Agreed Capacity to [Section 5.6.1](#561-detailed-description-of-capacity-data) +- Added Repositories to [Annexes](#annexes) +- Updated References in [Chapter 7](#7-references) +- Updated `WeekBasedCapacityGroup` aspect model +- Updated `WeekBasedMaterialDemand` aspect model +- Updated `MessageHeaderAspect` version in [Chapter 4](#4-application-programming-interfaces) +- Updated Policies in [Chapter 6](#6-framework-agreement-and-policies) +- Updated choice of words and writing pattern throughout this standard + +### Release 24.03 + +- Merged CX-0046, CX-0047 and CX-0048 into this standard +- Replaced `WeekBasedMaterialDemand` with `MaterialDemand` aspect model +- Added Nesting of `WeekBasedCapacityGroup` to [Section 5.6.2](#562-weekbasedcapacitygroup-structure) +- Added [Section 5.6.4](#564-load-factors-for-weekbasedcapacitygroup) Load Factors +- Added [Section 5.7.2](#572-simulated-delta-production-pre-post-production) Simulated Delta-Production (Pre-/Post-production) +- Added [Chapter 5.8](#58-request-for-update-rfu) Request for Update +- Added [Chapter 5.9](#59-collaboration-functionalities-for-demand-and-capacity-management) Collaboration functionalities for DCM +- Updated `WeekBasedCapacityGroup` aspect model +- Updated unit of measure representation and handling + +### Release 23.09 + +- Initial release + +## 1 INTRODUCTION + +> *This section and all its subsections are non-normative* + +### 1.1 Audience and Scope + +This standard is intended for the three roles below, who are involved in the Demand and Capacity Management (DCM) process within the automotive industry: + +- Data Provider +- Data Consumer +- Business Application Provider + +For clarity on the roles and responsibility of each actor, please see [Chapter 5.2](#52-actors-and-roles). The scope of this standard includes regulations for managing future demands and capacities. It does not cover the specific methods companies use to calculate their demand or capacity data, nor does it address internal company measures. + +Illustrations and descriptions of roles are provided to help explain concepts and processes but are not mandatory. This standard requires that data consumers, providers and business application providers must adopt a uniform business logic, data models and data exchange protocols to ensure interoperable data exchange. + +This standard focuses on direct one-to-one business relationships between customers and suppliers. Companies participating in Catena-X DCM must have signed the DCM framework agreement. + +### 1.2 Context and Architecture Fit + +This standard (CX-0128) defines the standard data models and APIs for the following objects, utilized by the DCM use case: `WeekBasedMaterialDemand`, `WeekBasedCapacityGroup`, `IdBasedRequestForUpdate` and `IdBasedComment`. Applying these standards ensures that: + +- All actors participating in the DCM use case provide and consume demand-, capacity- and comment-information in an identical manner +- All actors participating in the DCM use case process data in an identical manner +- All actors participating in the DCM use case exchange data only via a connector conformant to [[CX-0018](#71-normative-references)] (e.g. Tractus-X EDC) +- All actors participating in the DCM use case interpret the exchanged data in an identical manner + +The APIs must only be used on the context of Catena-X and must only be accessible via a connector conformant to [[CX-0018](#71-normative-references)] (e.g. Tractus-X EDC). + +#### 1.2.1 Architectural Overview + +This standard covers the exchange of `WeekBasedMaterialDemand`, `WeekBasedCapacityGroup`, `IdBasedRequestForUpdate` and `IdBasedComment` data as JSON strings through a connector conformant to [[CX-0018](#71-normative-references)]. + +This standard also discusses the optional use of digital twin registries to support the transmission of `WeekBasedMaterialDemand` and `WeekBasedCapacityGroup` objects. + +How to build an application that creates and handles these objects is not part of this standard. + +### 1.3 Conformity and Proof of Conformity + +Non-mandatory sections include authoring guidelines, diagrams, examples and notes. All other content is mandatory. + +The capitalized key words such as **MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD** and **SHOULD NOT** are to be interpreted as defined in BCP 14 [[RFC2119](#72-non-normative-references)] [[RFC8174](#72-non-normative-references)]. + +Participants must demonstrate conformity with Catena-X standards. Conformity Assessment Bodies (CABs) verify that standards are correctly applied. + +**Proof of Conformity for Data Models** + +Participants must implement and conform to the standardized data models as described in [Chapter 3](#3-aspect-models). + +**Proof of Conformity for APIs** + +Participants must implement and conform to the standardized APIs as described in [Chapter 4](#4-application-programming-interfaces). + +**Proof of Conformity for Process and Core Business Logic** + +Participants must implement and conform to the DCM core business logic as described in [Chapter 5](#5-processes). + +### 1.4 Examples + +#### 1.4.1 Examples for Process and Core Business Logic + +Customers and suppliers must agree to the DCM framework agreement, implement the core business logic from [Chapter 5](#5-processes) and manage their access authorizations. They should ensure that material demand and capacity data are accurate, regularly updated and shared in a standardized format. + +Business application providers must implement APIs as described in this standard and enforce requirements for a trusted usage environment, contractual agreements and antitrust requirements. Their applications must also enforce process traceability and data sovereignty. + +#### 1.4.2 Examples for Data Models + +This section provides JSON examples for `WeekBasedMaterialDemand`, `WeekBasedCapacityGroup`, `IdBasedRequestForUpdate` and `IdBasedComment` payloads. The actual values must replace the placeholders in double curly braces. Further property descriptions are available in [Chapter 5](#5-processes). + +##### 1.4.2.1 WeekBasedMaterialDemand data model JSON structure + +> value-only payload serialization example + +```json +{ + "unitOfMeasureIsOmitted" : false, + "unitOfMeasure" : "unit:piece", + "materialDescriptionCustomer" : "Spark Plug", + "materialGlobalAssetId" : "urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df", + "materialDemandId" : "0157ba42-d2a8-4e28-8565-7b07830c1110", + "materialNumberSupplier" : "MNR-8101-ID146955.001", + "supplier" : "{{CATENAX-SUPPLIER-BPNL}}", + "changedAt" : "2023-11-05T08:15:30.123-05:00", + "demandSeries" : [ { + "expectedSupplierLocation" : "{{CATENAX-SUPPLIER-BPNS}}", + "demands" : [ { + "demand" : 1000, + "pointInTime" : "2023-10-09" + } ], + "customerLocation" : "{{CATENAX-CUSTOMER-BPNS}}", + "demandCategory" : { + "demandCategoryCode" : "0001" + } + } ], + "materialDemandIsInactive" : true, + "materialNumberCustomer" : "MNR-7307-AU340474.002", + "customer" : "{{CATENAX-CUSTOMER-BPNL}}" +} +``` + +##### 1.4.2.2 WeekBasedCapacityGroup data model JSON structure + +> value-only payload serialization example + +```json +{ + "unitOfMeasure" : "unit:piece", + "linkedDemandSeries" : [ { + "loadFactor" : 3.5, + "materialNumberCustomer" : "MNR-7307-AU340474.002", + "materialNumberSupplier" : "MNR-8101-ID146955.001", + "customerLocation" : "{{CATENAX-CUSTOMER-BPNS}}", + "demandCategory" : { + "demandCategoryCode" : "0001" + } + } ], + "linkedCapacityGroups" : [ "be4d8470-2de6-43d2-b5f8-2e5d3eebf3fd" ], + "unitOfMeasureIsOmitted" : false, + "capacityGroupIsInactive" : true, + "demandVolatilityParameters" : { + "rollingHorizonAlertThresholds" : [ { + "sequenceNumber" : 1, + "absoluteNegativeDeviation" : 100.0, + "subhorizonLength" : 4, + "relativeNegativeDeviation" : 0.3, + "absolutePositiveDeviation" : 100.0, + "relativePositiveDeviation" : 0.2 + } ], + "measurementInterval" : 4, + "startReferenceDateTime" : "2024-01-10T12:00:00.320Z" + }, + "supplier" : "{{CATENAX-SUPPLIER-BPNL}}", + "name" : "Spark Plugs on drilling machine for car model XYZ", + "supplierLocations" : [ "{{CATENAX-SUPPLIER-BPNS}}" ], + "capacities" : [ { + "pointInTime" : "2022-08-01", + "agreedCapacity" : 1800, + "actualCapacity" : 1000, + "maximumCapacity" : 2000, + "deltaProductionResult" : 400 + } ], + "changedAt" : "2023-03-10T12:27:11.320Z", + "capacityGroupId" : "0157ba42-d2a8-4e28-8565-7b07830c1110", + "customer" : "{{CATENAX-CUSTOMER-BPNL}}" +} +``` + +##### 1.4.2.3 IdBasedRequestForUpdate data model JSON structure + +> value-only payload serialization example + +```json +{ + "weekBasedMaterialDemand" : [ { + "materialDemandId" : "0157ba42-d2a8-4e28-8565-7b07830c3456", + "changedAt" : "2023-03-10T12:27:11.320Z" + } ], + "weekBasedCapacityGroup" : [ { + "capacityGroupId" : "0157ba42-d2a8-4e28-8565-7b07830c1110", + "changedAt" : "2023-03-10T12:27:11.320Z" + } ] +} +``` + +##### 1.4.2.4 IdBasedComment data model JSON structure + +> value-only payload serialization example + +```json +{ + "postedAt" : "2023-03-10T12:27:11.320Z", + "listOfReferenceDates" : [ "2023-11-05" ], + "author" : "someone@company.com", + "supplier" : "{{CATENAX-SUPPLIER-BPNL}}", + "commentType" : "information", + "commentId" : "f5c151e4-30b5-4456-94fd-2a7b559b6121", + "changedAt" : "2023-03-10T12:27:11.320Z", + "commentText" : "Hello, this is a comment!", + "requestDelete" : true, + "objectId" : "dfeb1334-497e-4dab-97c1-4e6f4e1c0320", + "objectType" : "urn:samm:io.catenax.week_based_capacity_group", + "customer" : "{{CATENAX-CUSTOMER-BPNL}}" +} +``` + +### 1.5 Terminology + +| Term | Description | +|:----------------|:---------------------------------------------------------------------------------------------------------------| +| Actual Capacity | This is the capacity a supplier realistically plans to have available to produce a certain amount of material per week for a customer. It takes into account the supplier's own assessment of their capabilities, inventory and existing commitments. | +| Agreed Capacity | May be coordinated between customer and supplier. The agreed capacity must not constitute a legal obligation to deliver. Using the agreed capacity is optional and has purely informative character. The agreed capacity may be greater than, less than or equal to the actual or maximum capacity of the supplier. It may be used for a time frame shorter than the whole time series. | +| Aspect Model | An Aspect model is a structured, machine-readable description of data. It utilizes the Turtle file format to serialize a Resource Description Framework (RDF) graph, that relates to a specific aspect. It must follow the Semantic Aspect Meta Model (SAMM) guidelines, meaning it uses defined elements and rules from SAMM. Aspect models help to clarify the meaning of data at runtime and should link to standardized business glossary terms, if available. | +| Bottleneck | A facility, function, department, or resource whose capacity is less than the demand placed upon it. For example, a bottleneck machine or work center exists where jobs are processed at a slower rate than they are demanded (Source: ASCM Supply Chain Dictionary, 17th edition). | +| Business application provider | Offers tools for demand and capacity management that conform to the core business logic, data models and APIs described in this standard. | +| Business Partner Number Legal Entity (BPNL) | A BPNL is an unique identifier for a company or partner within the Catena-X network. | +| Business Partner Number Site (BPNS) | A BPNS is an unique identifier for a specific location, such as a factory, within the Catena-X network. | +| Calendar Week | A week consisting of seven days, typically numbered according to the week containing the year's first Thursday. For example, if the first Thursday of the year is on January 1st, that week is considered Week 1. | +| Capacity | 1. The capability of a system to perform its expected function. 2. The capability of a worker, machine, work center, plant, or organization to produce output per time period. (Source: ASCM Supply Chain Dictionary, 17th edition). | +| Capacity Group | A Capacity Group is where material demand and capacity information are matched for collaborative planning. When written as `WeekBasedCapacityGroup`, it refers to a specific data model within this standard. | +| Comment | A feature that allows two business partners to exchange messages about material demand and capacity, facilitating direct collaboration and quick issue resolution. | +| Comments | These are purely text-based exchanges without the transfer of documents or attachments. | +| CreationEntity | Currently, a Creation Entity groups `WeekBasedCapacityGroup` objects to support digital twins in the planning process. It may represent a production plant and will be further defined in future revisions of this standard. | +| Customer | A role within the DCM use case. Receives goods from its suppliers. Participating companies can have multiple roles at the same time. Customers provide consistent and up-to-date demand forecast and receive capacity data from suppliers. | +|(Simulated) Delta-Production | This is an optional feature that allows suppliers to manage capacity bottlenecks by simulating changes in production without altering actual or maximum capacity. | +| Demand Deviation | This is an optional metric that allows suppliers to monitor changes in customer demands and to identify significant changes that can collaboratively be addressed by suppliers and customers. | +| Digital Twin | Based on [[CX-0002](#71-normative-references)] Standard a digital twin (DT) describes a digital representation of an asset sufficient to meet the requirements of a set of use cases. For detailed information please refer to [[CX-0002](#71-normative-references)] Digital Twins in Catena-X. | +| Flexible Capacity | The difference between maximum and actual capacity, representing the potential to increase capacity without further agreements, such as extending the use of production resources within a week. In particular, it refers to measures to extend the weekly utilization of the available production resources. | +| Linking material demand | Material demands can be linked directly to a capacity group or indirectly through another capacity group, which is known as "Nesting." | +| Load Factor | Optional feature of a capacity group. ~ adds individual numerical material load factors to `WeekBasedMaterialDemand` linked by the `WeekBasedCapacityGroup`. ~ adds flexibility to the unit of measure of the capacity group. | +| Material | The elements, constituents, or substances of which something is composed or can be made. Usually referred to by a material number. | +| (Material) demand | A need for a particular product or component. The demand could come from any number of sources (e.g., a customer order or forecast, an interplant requirement, a branch warehouse request for a service part, or the manufacturing of another product). At the finished goods level, demand data is usually different from sales data because demand does not necessarily result in sales (i.e., If there is no stock, there will be no sale (Source: ASCM Supply Chain Dictionary, 17th edition)). Material demand may comprise multiple demand series by location and demand categories. When the term is written as one word (`WeekBasedMaterialDemand`), the term refers specifically to the respective aspect model. | +| Maximum Capacity | Is the maximum releasable capacity of a supplier which should be possible to achieve a material output per calendar week with a certain unit of measure for one customer. The maximum capacity is based on capacity-increasing measures, agreed by the parties involved. Capacity-increasing measures can be, for example, a longer utilization of the available production resources, a shift extension or additional shifts. Secondarily, additional resources can also be activated. | +| Nesting | A method by which a capacity group links another capacity group, allowing for dynamic changes and centralized data management. | +| Supplier | A role within the DCM use case. Supplies goods to its customers. Participating companies can have multiple roles at the same time. Suppliers provide consistent and up-to-date capacity data and receive demands from customers. | +| Surplus | A surplus is a situation in which an oversupply exists. | +| WeekBasedCapacityGroup | This term refers to the specific `WeekBasedCapacityGroup` object defined in this standard. | + +For additional terminology, please refer to the glossary on the association's homepage. + +## 2 RELEVANT PARTS OF THIS STANDARD FOR SPECIFIC USE CASES + +> *This section and all its subsections are normative* + +This chapter lists all aspects of this standard that directly impact other Catena-X use cases if modified. + +### 2.1 Digital Twins + +This standard utilizes digital twins of "part type" (BOM as planned). Digital twins of "part instance" (BOM as built) are not utilized. Part type twins are also relevant to various other Catena-X standards. For additional details see [[CX-0126](#71-normative-references)] Industry Core: Part Type. + +### 2.2 Supply Chain Disruption Notifications + +This standard utilizes Supply Chain Disruption Notifications. Supply Chain Disruption Notifications are also relevant to other Catena-X standards. For additional details see [[CX-0146](#71-normative-references)] Supply Chain Disruption Notifications. + +### 2.3 Additional Requirements + +#### 2.3.1 Conventions for Use Case Policy in Context Data Exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been described. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to: + +- The detailed [[ODRL](#repositories)] policy repository. This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- The ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas MUST be followed when providing services or apps for data sharing/consuming. + +##### 2.3.1.1 Additional details regarding access policies + +A data provider may tie certain access authorizations `Access Policies` to its data offers for members of Catena-X and one or several data consumers. By limiting access to certain Participants, data provider maintains control over its anti-trust obligations when sharing certain data. In particular, data providers may apply access policies to restrict access to a particular data offer for only one participant identified by a specific business partner number. + +##### 2.3.1.2 Additional details regarding usage policies + +In the context of data usage policies `Usage Policies`, participants and related services MUST use the following policy rules: + +- Use Case Framework `FrameworkAgreement` +- At least one use case purpose `UsagePurpose` from the above mentioned [[ODRL](#repositories)] policy repository. + +Additionally, respective usage policies MAY include the following policy rule: + +- Reference Contract `ContractReference`. + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the [[ODRL](#repositories)] policy repository. + +## 3 ASPECT MODELS + +> *This section and all its subsections are normative* + +### 3.1 Aspect Model WeekBasedMaterialDemand + +#### 3.1.1 Introduction + +For the exchange of material demand information, customers MUST provide data to suppliers. The data format specified in this standard MUST be conformed to. + +Customers and suppliers MUST implement the `WeekBasedMaterialDemand` data model. + +Suppliers MUST be able to consume and process material demand information. + +Customers MUST be able to provide and process material demand information. + +Data providers of `WeekBasedMaterialDemand` data MUST ensure that it aligns with the semantic model specified in this standard. + +The unique identifier for the semantic model, as specified in this standard, MUST be used to define the meaning of the data being transferred. + +Business applications utilizing `WeekBasedMaterialDemand` data MUST consume this data, conforming to the semantic model specified in this standard. + +This semantic model MUST be made available in the central Semantic Hub. + +Data consumers and data providers MUST comply with the license of the semantic model specified in [Section 3.1.3](#313-license). + +Within the Catena-X data space `WeekBasedMaterialDemand` data MUST be requested and exchanged using a connector, conforming to the standards [[CX-0018](#71-normative-references)] and [[CX-0002](#71-normative-references)]. + +The JSON Payload provided by data providers MUST comply with the JSON schema as specified in this standard. + +The characteristics BPNL and BPNS MUST be used, conforming with [[CX-0010](#71-normative-references)]. + +#### 3.1.2 Specification Artifacts + +The creation of the semantic model specified in this section followed a sematic driven workflow, conforming to [[SMT](#72-non-normative-references)]. +Conforming with [[CX-0003](#71-normative-references)] the resulting aspect model was written in SAMM 2.0.0 and is available on GitHub. + +#### 3.1.3 License + +This Catena-X data model is released under the [CC-BY-4.0](#72-non-normative-references) license. + +#### 3.1.4 Identifier of Semantic Model + +The semantic model has the unique identifier + +```text +urn:samm:io.catenax.week_based_material_demand:3.0.0 +``` + +Data providers MUST use this identifier to clearly define the semantics of the data they are transferring. + +#### 3.1.5 Formats of Semantic Model + +##### 3.1.5.1 RDF turtle + +All other file format and serializations are derived from a RDF turtle file. It is the source for the Semantic Aspect Meta Model. You can access the RDF turtle file at the following URL: + +```text +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.week_based_material_demand/3.0.0/WeekBasedMaterialDemand.ttl +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used to generate other file formats such as JSON schema, AASX for Asset Administration Shell Submodel template or HTML documentation. + +##### 3.1.5.2 JSON schema + +A JSON schema, which describes the structure of the data payload, can be created from the RDF turtle file. This schema specifically describes the data format for the `GetSubmodel` API operation within the Asset Administration Shell, focusing on the values without including semantic information. This allows for a clear and structured way to retrieve data from the API. + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF turtle file. The AASX file defines one of the requested artifacts for a Submodel template specification conformant to [[SMT](#72-non-normative-references)]. + +#### 3.1.6 Semantic Model + +Not applicable. + +### 3.2 Aspect Model WeekBasedCapacityGroup + +#### 3.2.1 Introduction + +For the exchange of capacity group information, suppliers MUST provide data to customers. The data format specified in this standard MUST be conformed to. + +Customers and suppliers MUST implement the `WeekBasedCapacityGroup` data model. + +Suppliers MUST be able to provide and process capacity group information. + +Customers MUST be able to consume and process capacity group information. + +Data providers of `WeekBasedCapacityGroup` data MUST ensure that it aligns with the semantic model specified in this standard. + +The unique identifier for the semantic model, as specified in this standard, MUST be used to define the meaning of the data being transferred. + +Business applications utilizing `WeekBasedCapacityGroup` data MUST consume this data, conforming to the semantic model specified in this standard. + +This semantic model MUST be made available in the central Semantic Hub. + +Data consumers and data providers MUST comply with the license of the semantic model specified in [Section 3.2.3](#323-license). + +Within the Catena-X data space `WeekBasedCapacityGroup` data MUST be requested and exchanged using a connector, conforming to the standards [[CX-0018](#71-normative-references)] and [[CX-0002](#71-normative-references)]. + +The JSON Payload provided by data providers MUST comply with the JSON schema as specified in this standard. + +The characteristics BPNL and BPNS MUST be used, conforming with [[CX-0010](#71-normative-references)]. + +#### 3.2.2 Specification Artifacts + +The creation of the semantic model specified in this section followed a sematic driven workflow, conforming to [[SMT](#72-non-normative-references)]. +Conforming with [[CX-0003](#71-normative-references)] the resulting aspect model was written in SAMM 2.0.0 and is available on GitHub. + +#### 3.2.3 License + +This Catena-X data model is released under the ([CC-BY-4.0](#72-non-normative-references)) license. + +#### 3.2.4 Identifier of Semantic Model + +The semantic model has the unique identifier + +```text +urn:samm:io.catenax.week_based_capacity_group:3.0.0 +``` + +Data providers MUST use this identifier to clearly define the semantics of the data they are transferring. + +#### 3.2.5 Formats of Semantic Model + +##### 3.2.5.1 RDF turtle + +All other file format and serializations are derived from a RDF turtle file. It is the source for the Semantic Aspect Meta Model. You can access the RDF turtle file at the following URL: + +```text +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.week_based_capacity_group/3.0.0/WeekBasedCapacityGroup.ttl +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used to generate other file formats such as JSON schema, AASX for Asset Administration Shell Submodel template or HTML documentation. + +##### 3.2.5.2 JSON schema + +A JSON schema, which describes the structure of the data payload, can be created from the RDF turtle file. This schema specifically describes the data format for the `GetSubmodel` API operation within the Asset Administration Shell, focusing on the values without including semantic information. This allows for a clear and structured way to retrieve data from the API. + +##### 3.2.5.3 AASX + +An AASX file can be generated from the RDF turtle file. The AASX file defines one of the requested artifacts for a Submodel template specification conformant to [[SMT](#72-non-normative-references)]. + +#### 3.2.6 Semantic Model + +Not applicable. + +### 3.3 Aspect Model IdBasedRequestForUpdate + +#### 3.3.1 Introduction + +`IdBasedRequestForUpdate` can be exchanged between customer and supplier conforming to the API standard described in [Chapter 4.3](#43-requestforupdate-api). The data format specified in this standard MUST be conformed to. + +Customers and suppliers MUST implement the `IdBasedRequestForUpdate` data model. + +Customers and suppliers MUST be able to consume and process a request for update. + +Providing an `IdBasedRequestForUpdate` is OPTIONAL. It is RECOMMENDED to be both capable of providing and consuming a request for update. + +Providers of an `IdBasedRequestForUpdate` MUST ensure that it aligns with the semantic model specified in this standard. + +The unique identifier for the semantic model, as specified in this standard, MUST be used to define the meaning of the data being transferred. + +Business applications utilizing `IdBasedRequestForUpdate` data MUST consume this data, conforming to the semantic model specified in this standard. + +This semantic model MUST be made available in the central Semantic Hub. + +Data consumers and data providers MUST comply with the license of the semantic model specified in [Section 3.3.3](#333-license). + +Within the Catena-X data space `IdBasedRequestForUpdate` data MUST be requested and exchanged using a connector, conforming to the standards [[CX-0018](#71-normative-references)] and [[CX-0002](#71-normative-references)]. + +The JSON Payload provided by data providers MUST comply with the JSON schema as specified in this standard. + +#### 3.3.2 Specification Artifacts + +The creation of the semantic model specified in this section followed a sematic driven workflow, conforming to [[SMT](#72-non-normative-references)]. +Conforming with [[CX-0003](#71-normative-references)] the resulting aspect model was written in SAMM 2.0.0 and is available on GitHub. + +#### 3.3.3 License + +This Catena-X data model is released under the ([CC-BY-4.0](#72-non-normative-references)) license. + +#### 3.3.4 Identifier of Semantic Model + +The semantic model has the unique identifier + +```text +urn:samm:io.catenax.id_based_request_for_update:3.0.0 +``` + +Data providers MUST use this identifier to clearly define the semantics of the data they are transferring. + +#### 3.3.5 Formats of Semantic Model + +##### 3.3.5.1 RDF turtle + +All other file format and serializations are derived from a RDF turtle file. It is the source for the Semantic Aspect Meta Model. You can access the RDF turtle file at the following URL: + +```text +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.id_based_request_for_update/3.0.0/IdBasedRequestForUpdate.ttl +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used to generate other file formats such as JSON schema, AASX for Asset Administration Shell Submodel template or HTML documentation. + +##### 3.3.5.2 JSON schema + +A JSON schema, which describes the structure of the data payload, can be created from the RDF turtle file. This schema specifically describes the data format for the `GetSubmodel` API operation within the Asset Administration Shell, focusing on the values without including semantic information. This allows for a clear and structured way to retrieve data from the API. + +##### 3.3.5.3 AASX + +An AASX file can be generated from the RDF turtle file. The AASX file defines one of the requested artifacts for a Submodel template specification conformant to [[SMT](#72-non-normative-references)]. + +#### 3.3.6 Semantic Model + +Not applicable. + +### 3.4 Aspect Model IdBasedComment + +#### 3.4.1 Introduction + +An `IdBasedComment` can refer to a `WeekBasedCapacityGroup`, its weekly capacities, a `WeekBasedMaterialDemand`, or its weekly demand series. This comment can be exchanged between customer and supplier conforming to the API standard described in [Chapter 4.4](#44-idbasedcomment-api). The data format specified in this standard MUST be conformed to. + +Customers and suppliers MUST implement the `IdBasedComment` data model. + +Customers and suppliers MUST be able to provide and process an `IdBasedComment`. + +Customers and suppliers MUST be able to consume and process an `IdBasedComment`. + +Data providers of `IdBasedComment` data MUST ensure that it aligns with the semantic model specified in this standard. + +The unique identifier for the semantic model, as specified in this standard, MUST be used to define the meaning of the data being transferred. + +Business applications utilizing `IdBasedComment` data MUST consume this data, conforming to the semantic model specified in this standard. + +This semantic model MUST be made available in the central Semantic Hub. + +Data consumers and data providers MUST comply with the license of the semantic model specified in [Section 3.4.3](#343-license). + +Within the Catena-X data space `IdBasedComment` data MUST be requested and exchanged using a connector, conforming to the standards [[CX-0018](#71-normative-references)] and [[CX-0002](#71-normative-references)]. + +The JSON Payload provided by data providers MUST comply with the JSON schema as specified in this standard. + +The characteristics BPNL and BPNS MUST be used, conforming with [[CX-0010](#71-normative-references)]. + +#### 3.4.2 Specification Artifacts + +The creation of the semantic model specified in this section followed a sematic driven workflow, conforming to [[SMT](#72-non-normative-references)]. +Conforming with [[CX-0003](#71-normative-references)] the resulting aspect model was written in SAMM 2.0.0 and is available on GitHub. + +#### 3.4.3 License + +This Catena-X data model is released under the ([CC-BY-4.0](#72-non-normative-references)) license. + +#### 3.4.4 Identifier of Semantic Model + +The semantic model has the unique identifier + +```text +urn:samm:io.catenax.id_based_comment:1.0.0 +``` + +Data providers MUST use this identifier to clearly define the semantics of the data they are transferring. + +#### 3.4.5 Formats of Semantic Model + +##### 3.4.5.1 RDF turtle + +All other file format and serializations are derived from a RDF turtle file. It is the source for the Semantic Aspect Meta Model. You can access the RDF turtle file at the following URL: + +```text +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.id_based_comment/1.0.0/IdBasedComment.ttl +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used to generate other file formats such as JSON schema, AASX for Asset Administration Shell Submodel template or HTML documentation. + +##### 3.4.5.2 JSON schema + +A JSON schema, which describes the structure of the data payload, can be created from the RDF turtle file. This schema specifically describes the data format for the `GetSubmodel` API operation within the Asset Administration Shell, focusing on the values without including semantic information. This allows for a clear and structured way to retrieve data from the API. + +##### 3.4.5.3 AASX + +An AASX file can be generated from the RDF turtle file. The AASX file defines one of the requested artifacts for a Submodel template specification conformant to [[SMT](#72-non-normative-references)]. + +#### 3.4.6 Semantic Model + +Not applicable. + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section and all its subsections are normative* + +**HEADER** + +When exchanging data with a DCM partner, the POST request payload MUST be structured as follows: + +```json +{ + "messageHeader": + , + + "content":{ + "informationObject":[ + , + + ] + } +} +``` + +This format ensures that the header, which contains metadata about the message, is kept separate from the content, which includes the actual data being exchanged. The content section can hold multiple `informationObject` entries. These objects can be one of the following types: `WeekBasedMaterialDemand`, `WeekBasedCapacityGroup`, `IdBasedComment`, or `IdBasedRequestForUpdate`. + +The master reference for generating additional file formats and serializations is the RDF turtle file, which is an instance of the Semantic Aspect Meta Model. The RDF turtle file for the `messageHeaderObject` is defined in a centralized shared aspect model and can be accessed at the following URL: + +```text +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shared.message_header/3.0.0/MessageHeaderAspect.ttl +``` + +Within the RDF turtle file, you will find detailed descriptions for how to use the message header. + +### 4.1 WeekBasedMaterialDemand API + +The `WeekBasedMaterialDemand` object is used to provide material demand information from customer to supplier. + +Customers MUST be able to provide `WeekBasedMaterialDemand`. + +Suppliers MUST be able to consume and process `WeekBasedMaterialDemand`. + +#### 4.1.1 Preconditions and Dependencies + +The `WeekBasedMaterialDemand` API MUST be published towards the network using a Data Asset/Contract Offer, which is in line with the Dataspace Protocol as specified by the International Data Spaces Association (IDSA) and MUST conform with the Catena-X standard [[CX-0001](#71-normative-references)]. + +#### 4.1.2 API Specification + +##### 4.1.2.1 API endpoints and resources + +The API requires a single endpoint that accepts HTTP POST requests as described in [[RFC9110](#72-non-normative-references)]. The specific structure of the endpoint MAY vary, but its address MUST be included in the Data Asset as defined in [Section 4.1.2.5](#4125-data-asset-structure). + +##### 4.1.2.2 Data exchange + +Customers MUST provide suppliers with `WeekBasedMaterialDemand` data via HTTP POST request. The data MUST conform to the format specified in this standard and it MUST NOT exceed 15 MiB in size. It MUST be a valid JSON string and MUST include all mandatory properties. The data model with all its properties MUST conform to the respective aspect model and the definitions in [Chapter 3.1](#31-aspect-model-weekbasedmaterialdemand) as well as [Units of measure used in DCM](#units-of-measure-used-in-dcm). Properties marked as "optional" MAY be included in the data. +When consuming a payload, that contains unknown properties not described within the data model but is otherwise correct, those properties MUST be ignored. + +Attributes that are strings MUST be formatted correctly. For example, `expectedSupplierLocation` MUST be formatted as a BPNS. The `pointInTime` property MUST represent the week's Monday in the format YYYY-MM-DD as described in [[ISO8601](#72-non-normative-references)]. + +The `demandCategory` property MUST be set to one of the predefined values from [Section 5.5.1](#551-detailed-description-of-demand-data). + +The `unitOfMeasure` property MUST be set to one of the predefined values from [Units of measure used in DCM](#units-of-measure-used-in-dcm). If no unit of measure is to be provided, the customer MUST omit the property and set the `unitOfMeasureIsOmitted` flag to true. + +Multiple `WeekBasedMaterialDemand` aspects MAY be provided in one transfer as a JSON list. If only one `WeekBasedMaterialDemand` aspect is provided, it MUST be as list with one entry. + +The current week is denominated as N=0, the next week as N=1, the week after the next week as N=2 and so on. +The data series in the `WeekBasedMaterialDemand` SHOULD start from week N=2. The dataset MUST include at least one week, where N>1 and MUST NOT contain duplicate weeks. Weeks N=0 and N=1 MAY be included. If demand changes, the entire dataset MUST be provided again, avoiding inconsistent or incomplete data. The new dataset might contain additional data or less data than the previous version of the same dataset. This includes the possibility that a `demandSeries` might have been removed entirely. Each `WeekBasedMaterialDemand` object MUST be unique for a given `supplier`, `customer` and `materialNumberCustomer` combination. This means that customers need to aggregate demands from all their factories before providing them to suppliers as a single `WeekBasedMaterialDemand`. + +If a week's demand is zero (value = `0`), it MUST be explicitly stated and included in the `WeekBasedMaterialDemand`, unknown demands (value = `null`) SHOULD be omitted. + +The customer MAY define a `WeekBasedMaterialDemand` as inactive by setting and transferring the `materialDemandIsInactive` flag to the supplier. The inactive `WeekBasedMaterialDemand` and their related `demandSeries` data MUST be ignored during the demand-capacity matching over the whole horizon, i.e. must be considered in the same way as not existing data for the demand-capacity matching. Inactivating a `WeekBasedMaterialDemand` may trigger their archiving or deletion in the local DCM application of the business partner. +Once a `WeekBasedMaterialDemand` has been set as inactive, this MAY be undone by the customer by reverting the `materialDemandIsInactive` flag. In this case, the `WeekBasedMaterialDemand` MUST again be considered during the demand-capacity matching. The reverting of the inactive flag of a `WeekBasedMaterialDemand` may correspond to a newly created and initially transferred or to an updated `WeekBasedMaterialDemand`. + +##### 4.1.2.3 UUID generation and handling + +UUIDv4 is REQUIRED for exchanging demand data to ensure uniqueness and security. The UUID MUST be generated conforming to [[RFC4122](#72-non-normative-references)] and MUST be treated as unique within the supplier-customer relationship. + +See [Section 4.1.2.7](#4127-validating-payload) for further handling information. + +##### 4.1.2.4 Available data types + +The API MUST use JSON formatted data transmitted over HTTPS. + +##### 4.1.2.5 Data asset structure + +The HTTP POST endpoint introduced in [Section 4.1.2.1](#4121-api-endpoints-and-resources) MUST NOT be called from a supply chain partner directly. Rather, it MUST be called via connector conformant to [[CX-0018](#71-normative-references)]. Therefore, the endpoint MUST be offered as a Data Asset. The latter MUST have a property `https://purl.org/dc/terms/type` with the ID `https://w3id.org/catenax/taxonomy#DcmWeekBasedMaterialDemand`. It can be abbreviated if the namespaces of key and value are part of the json-ld @context object (see example below). This property SHOULD be used to identify the asset when searching the assets catalog of a supplier. Because the asset reflects the contractual relationship between a supplier and its customers, only one asset with the aforementioned property for one version MUST be visible to the customer at any time to avoid ambiguity. + +The API version described in this standard MUST be published in the property `https://w3id.org/catenax/ontology/common#version` as version 2.0 in the asset. The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +Each supplier MUST ensure that only their customers have access to the asset by using access and usage policies and respective contract definitions. + +An example Data Asset definition is shown below. + +> Note: Expressions in double curly braces \{\{\}\} MUST be substituted with a corresponding value. +> +> Asset definition example for Management API v3 (non-normative) + +```json +{ + "@context": { + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@id": "{{ ASSET_ID }}", + "properties": { + "dct:type": { + "@id": "cx-taxo:DcmWeekBasedMaterialDemand" + }, + "description": "Endpoint for providing Material Demands", + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ URL-BACKEND-APPLICATION-WEEKBASEDMATERIALDEMAND-ENDPOINT }}", + "method": "POST", + "proxyBody": "true", + "contentType": "application/json" + } +} +``` + +##### 4.1.2.6 Error handling + +Every API endpoint defined in [Section 4.1.2.1](#4121-api-endpoints-and-resources) MUST respond to incoming requests with HTTP status codes as described in [[RFC9110](#72-non-normative-references)]. All of the following HTTP status codes, except for codes `200` and `201`, MUST be interpreted as failures. Therefore, it may be sufficient for a business application to simply check if the status code is `200` or `201` or not. If not, the request failed. + +| HTTP Status Code | HTTP Status Message | Description | +|:-----------------|:--------------------|:-------------| +| 200 | OK | The request has succeeded. The `WeekBasedMaterialDemand` has been successfully processed in the backend system. | +| 201 | Created | The request has succeeded and has led to the creation of a new `WeekBasedMaterialDemand` in the backend system. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g. malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | The client request has not been completed because it lacks valid authentication credentials for the requested resource. | +| 403 | Forbidden | The `WeekBasedMaterialDemand` in question is not available for the client (e.g. it belongs to a different company). | +| 405 | Method not allowed | The method used to request the data was not POST. | +| 422 | Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors, e.g. the JSON payload could not be parsed. | +| 503 | Service Unavailable | The server is not ready to handle the request. | + +If one `WeekBasedMaterialDemand` aspect is provided in one HTTP request, the return codes MUST be used as stated in the table above. + +If a list of multiple `WeekBasedMaterialDemand` aspects is provided in one HTTP request, the status code `400` MUST be used if at least one `WeekBasedMaterialDemand` in the list cannot be processed. Applications MAY choose to process valid entries from a list which also contains invalid entries. If a list of multiple `WeekBasedMaterialDemand` aspects is provided in one HTTP request and all of them can be processed successfully, the status code `200` MUST be used. + +The return codes `401`, `405`, `422` and `503` in the table above MAY also be applicable to a list of multiple `WeekBasedMaterialDemand` aspects. + +##### 4.1.2.7 Validating payload + +The following tables are supposed to answer questions regarding what business logic MUST be executed when consuming a `WeekBasedMaterialDemand` which has been formed in a specific way. + +The order of rules is indicated by the 'Number' row. The rules MUST be executed in exactly this order, starting from the lowest number. + +The first rule that matches MUST be executed. All other rules MUST be ignored. + +'value' indicates the actual value written in quotation marks and without any specific formatting (e.g. italic). + +*Valid value* indicates that the value is valid according to aspect model, API and process. + +*Invalid value* indicates that the value is invalid according to aspect model, API and process. + +*Any value* indicates that the value can be anything, valid or not. + +A whitespace or an empty cell indicates that for this specific rule that row is not applicable. + +| **Number** | 1 | | +|---|---|---| +| **Properties** | | | +| **Meta Properties** | Any property | *Invalid value* | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 2 | | +|---|---|---| +| **Properties** | customer | Customer BPNL does not match the providing connectors registered BPNL | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 3 | | +|---|---|---| +| **Properties** | customer | Supplier does not match any Supplier BPNL that I am responsible for | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 4 | | +|---|---|---| +| **Properties** | materialDemandID | *Known value* | +| | changedAt | More recent than all previously consumed `WeekBasedMaterialDemand` with the same materialDemandID | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Overwrite all existing values | +| | Return Code | 200 - OK | + +| **Number** | 5 | | +|---|---|---| +| **Properties** | materialDemandID | *Unknown value*, but there exists another UUID for the exact same combination of supplier, customer and materialNumberCustomer | +| | customer | *Known value* | +| | supplier | *Known value* | +| | materialNumberCustomer | *Known value* | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 6 | | +|---|---|---| +| **Properties** | materialDemandID | *Unknown value* | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Save as new material demand with consumed values | +| | Return Code | 201 - Created | + +| **Number** | 7 | | +|---|---|---| +| **Properties** | materialDemandID | *Known value* | +| | changedAt | Older than any previously consumed `WeekBasedMaterialDemand` with the same materialDemandID | +| **Meta Properties** | Any property | | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 8 | | +|---|---|---| +| **Properties** | materialDemandID | *Known value* | +| | changedAt | Identical to the most recent of all previously consumed `WeekBasedMaterialDemand` with the same materialDemandID | +| **Meta Properties** | Any property | | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Overwrite all existing values with consumed values | +| | Return Code | 200 - OK | + +### 4.2 WeekBasedCapacityGroup API + +The `WeekBasedCapacityGroup` object is used to provide capacity group information from supplier to customer. + +Suppliers MUST be able to provide `WeekBasedCapacityGroup` + +Customers MUST be able to consume and process `WeekBasedCapacityGroup` + +#### 4.2.1 Preconditions and Dependencies + +The `WeekBasedCapacityGroup` API MUST be published towards the network using a Data Asset/Contract Offer, which is in line with the Dataspace Protocol as specified by IDSA and MUST conform with the Catena-X standard [[CX-0001](#71-normative-references)]. + +#### 4.2.2 API Specification + +##### 4.2.2.1 API endpoints and resources + +The API requires a single endpoint that accepts HTTP POST requests as described in [[RFC9110](#72-non-normative-references)]. The specific structure of the endpoint MAY vary, but its address MUST be included in the Data Asset as defined in [Section 4.1.2.5](#4125-data-asset-structure). + +##### 4.2.2.2 Data exchange + +Suppliers MUST provide customers with `WeekBasedCapacityGroup` data via HTTP POST request. The data MUST conform to the format specified in this standard and it MUST NOT exceed 15 MiB in size. It MUST be a valid JSON string and MUST include all mandatory properties. The data model with all its properties MUST conform to the respective aspect model and the definitions in [Chapter 3.2](#32-aspect-model-weekbasedcapacitygroup) as well as in [Units of measure used in DCM](#units-of-measure-used-in-dcm). Properties marked as "optional" MAY be included in the data. +When consuming a payload, that contains unknown properties not described within the data model but is otherwise correct, those properties MUST be ignored. + +Attributes that are strings MUST be formatted correctly. For example, `customer` MUST be formatted as a BPNL. The `pointInTime` property MUST represent the week's Monday in the format YYYY-MM-DD as described in [[ISO8601](#72-non-normative-references)]. + +The `demandCategory` property MUST be set to one of the predefined values from [Section 5.5.1](#551-detailed-description-of-demand-data). + +The `unitOfMeasure` property MUST be set to one of the predefined values from [Units of measure used in DCM](#units-of-measure-used-in-dcm). If no unit of measure is to be provided, the customer MUST omit the property and set the `unitOfMeasureIsOmitted` flag to true. + +Multiple `WeekBasedCapacityGroup` aspects MAY be provided in one transfer as a JSON list. If only one `WeekBasedCapacityGroup` aspect is provided, it MUST be as a list with one entry. + +The current week is denominated as N=0, the next week as N=1, the week after the next week as N=2 and so on. +The data series in the `WeekBasedCapacityGroup` SHOULD start from N=2. The dataset MUST include at least one week, where N>1 and MUST NOT contain duplicate weeks. Weeks N=0 and N=1 MAY be included. If capacity changes, the entire dataset MUST be provided again, avoiding inconsistent or incomplete data. A single combination of `demandCategory`, `customerLocation` and `materialNumberCustomer` MAY be referenced across multiple `WeekBasedCapacityGroup` objects. This means that one `materialNumberCustomer` MAY appear in the `linkedDemandSeries` of several distinct `WeekBasedCapacityGroup` objects. + +If a week's demand is zero (value = `0`), it MUST be explicitly stated and included in the `WeekBasedMaterialDemand`, unknown demands (value = `null`) SHOULD be omitted. + +The `linkedDemandSeries` property specifies which particular `WeekBasedMaterialDemand` a `WeekBasedCapacityGroup` is referencing. To clarify the `linkedDemandSeries` points to a demand with a specific trio: `demandCategory`, `customerLocation` and `materialNumberCustomer`. + +The customer MAY define a `WeekBasedCapacityGroup` as inactive by setting and transferring the `capacityGroupIsInactive` flag to the supplier. The inactive `WeekBasedCapacityGroup` MUST be ignored during the demand-capacity matching over the whole horizon, i.e. must be considered in the same way as not existing data for the demand-capacity matching. Inactivating data may trigger their archiving or deletion in the local DCM application of the business partner. The inactive flag of a `WeekBasedCapacityGroup` MUST NOT affect linked `WeekBasedMaterialDemand` objects or other linked `WeekBasedCapacityGroup`. The inactivation of a `WeekBasedCapacityGroup` MAY result in the situation that its linked active `WeekBasedMaterialDemand` objects have to be newly linked to other active `WeekBasedCapacityGroup`. Once a `WeekBasedCapacityGroup` has been set as inactive, this MAY be undone by reverting the `capacityGroupIsInactive` flag. In this case, the `WeekBasedCapacityGroup` MUST again be considered during the demand-capacity matching. The reverting of the inactive flag of a `WeekBasedCapacityGroup` may correspond to a newly created and initially transferred or to an updated `WeekBasedCapacityGroup`. + +Suppliers MAY use demand volatility metrics, including the optional entity `demandVolatilityParameters` within the JSON payload. + +The following properties are used by demand volatility metrics: + +- demandVolatilityParameters + - startReferenceDateTime + - measurementInterval + - rollingHorizonAlertThresholds + - sequenceNumber + - subhorizonLength + - absolutePositiveDeviation + - absoluteNegativeDeviation + - relativePositiveDeviation + - relativeNegativeDeviation + +Suppliers use `startReferenceDateTime` to define the start of the demand volatility metric calculation, it is also marks the start of the first measurement interval. Its value MUST be chosen, so that transfer times are considered, allowing the customer to consume the data while `startReferenceDateTime` is still larger than the customer´s system time. It is RECOMMENDED to allow for a grace period of at least 24 hours. + +In order to get the start of any subsequent measurement intervals the value of `measurementInterval` needs to be converted from integer to weeks and added to `startReferenceDateTime`. + +Once demand volatility metric calculation has been initialized `startReferenceDateTime` MUST maintain its value. + +If the value of `startReferenceDateTime` or `measurementInterval` changes this is considered another initialization. + +For details, see [Chapter 3.2](#32-aspect-model-weekbasedcapacitygroup). + +The sequence of entries within the `linkedDemandSeries` of a `WeekBasedCapacityGroup` does not follow any particular order and MUST be treated as non-sequential or random. + +##### 4.2.2.3 UUID generation and handling + +UUIDv4 is REQUIRED for exchanging capacity data to ensure uniqueness and security. The UUID MUST be generated conforming to [[RFC4122](#72-non-normative-references)] and MUST be treated as unique within the supplier-customer relationship. + +See [Section 4.1.2.7](#4127-validating-payload) for further handling information. + +##### 4.2.2.4 Available data types + +The API MUST use JSON formatted data transmitted over HTTPS. + +##### 4.2.2.5 Data asset structure + +The HTTP POST endpoint introduced in [Section 4.2.2.1](#4221-api-endpoints-and-resources) MUST NOT be called from a supply chain partner directly. Rather, it MUST be called via a connector conformant to [[CX-0018](#71-normative-references)]. Therefore, the endpoint MUST be offered as a Data Asset. The latter MUST have a property `https://purl.org/dc/terms/type` with the ID `https://w3id.org/catenax/taxonomy#DcmWeekBasedCapacityGroup`. It can be abbreviated if the namespaces of key and value are part of the json-ld @context object (see example below). This property SHOULD be used to identify the asset when searching the assets catalog of a customer. Because the asset reflects the contractual relationship between a customer and its suppliers, only one asset with the aforementioned property for one version MUST be visible to the supplier at any time to avoid ambiguity. + +The API version described in this standard MUST be published in the property `https://w3id.org/catenax/ontology/common#version` as version 2.0 in the asset. The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +Each customer MUST ensure that only their suppliers have access to the asset by using access and usage policies and respective contract definitions. + +An example Data Asset definition is shown below. + +> Note: Expressions in double curly braces \{\{\}\} MUST be substituted with a corresponding value. +> +> Asset definition example for management API v3 (non-normative) + +```json +{ + "@context": { + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@id": "{{ ASSET_ID }}", + "properties": { + "dct:type": { + "@id": "cx-taxo:DcmWeekBasedCapacityGroup" + }, + "description": "Endpoint for providing Week Based Capacity Groups", + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ URL-BACKEND-APPLICATION-WEEKBASEDCAPACITYGROUP-ENDPOINT }}", + "method": "POST", + "proxyBody": "true", + "contentType": "application/json" + } +} +``` + +##### 4.2.2.6 Error handling + +Every API endpoint defined in [Section 4.2.2.1](#4221-api-endpoints-and-resources) MUST respond to incoming requests with HTTP status codes as described in [[RFC9110](#72-non-normative-references)]. All of the following HTTP status codes, except for codes `200` and `201`, MUST be interpreted as failures. Therefore, it may be sufficient for a business application to simply check if the status code is `200` or `201` or not. If not, the request failed. + +| HTTP Status Code | HTTP Status Message | Description | +|:-----------------|:--------------------|:-------------| +| 200 | OK | The request has succeeded. The `WeekBasedCapacityGroup` has been successfully processed in the backend system. | +| 201 | Created | The request has succeeded and has led to the creation of a new `WeekBasedCapacityGroup` in the backend system. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | The client request has not been completed because it lacks valid authentication credentials for the requested resource. | +| 403 | Forbidden | The `WeekBasedCapacityGroup` in question is not available for the client (e.g. it belongs to a different company). | +| 405 | Method not allowed | The method used to request the data was not POST. | +| 422 | Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors, e.g. the JSON payload could not be parsed. | +| 503 | Service Unavailable | The client request has not been completed because it lacks valid authentication credentials for the requested resource. | + +If one `WeekBasedCapacityGroup` aspect is provided in one HTTP request, the return codes MUST be used as stated in the table above. + +If a list of multiple `WeekBasedCapacityGroup` aspects is provided in one HTTP request, the status code `400` MUST be used if at least one `WeekBasedCapacityGroup` in the list cannot be processed. Applications MAY choose to process valid entries from a list which also contains invalid entries. If a list of multiple `WeekBasedCapacityGroup` aspects is provided in one HTTP request and all of them can be processed successfully, the status code `200` MUST be used. + +The return codes `401`, `405`, `422` and `503` in the table above MAY also be applicable to a list of multiple `WeekBasedCapacityGroup` aspects. + +##### 4.2.2.7 Validating payload + +The following tables are supposed to answer questions regarding what business logic MUST be executed when consuming a `WeekBasedCapacityGroup` which has been formed in a specific way. + +The order of rules is indicated by the 'Number' row. + +The first rule that matches MUST be executed. All other rules MUST be ignored. + +'value' indicates the actual value written in quotation marks and without any specific formatting (e.g. italic). + +*Valid value* indicates that the value is valid according to aspect model, API and process. + +*Invalid value* indicates that the value is invalid according to to aspect model, API and process. + +*Any value* indicates that the value can by anything, valid or not. + +A whitespace or an empty cell indicates that for this specific rule that row is not applicable. + +| **Number** | 1 | | +|---|---|---| +| **Properties** | | | +| **Meta Properties** | Any property | *Invalid value* | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 2 | | +|---|---|---| +| **Properties** | customer | Supplier BPNL does not match the providing connectors registered BPNL | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 3 | | +|---|---|---| +| **Properties** | customer | Customer does not match any Supplier BPNL that I am responsible for | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 4 | | +|---|---|---| +| **Properties** | linkedCapacityGroups | Either both `linkedCapacityGroups` and `linkedDemandSeries` contain *Any value* or do not contain a value. | +| | linkedDemandSeries | Either both `linkedCapacityGroups` and `linkedDemandSeries` contain *Any value* or do not contain a value. | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 5 | | +|---|---|---| +| **Properties** | startReferenceDateTime | *value* \< *system time* AND *value* \<\> *current value* of `startReferenceDateTime` | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore consumed values. | +| | Return Code | 400 - Bad Request | + +| **Number** | 6 | | +|---|---|---| +| **Properties** | capacityGroupID | *Known value* | +| | changedAt | More recent than all previously consumed `WeekBasedCapacityGroup` with the same capacityGroupID | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Overwrite all existing values | +| | Return Code | 200 - OK | + +| **Number** | 7 | | +|---|---|---| +| **Properties** | capacityGroupID | *Unknown value* | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Save as new capacity group with consumed values | +| | Return Code | 201 - Created | + +| **Number** | 8 | | +|---|---|---| +| **Properties** | capacityGroupID | *Known value* | +| | changedAt | Older than any previously consumed `WeekBasedCapacityGroup` with the same capacityGroupID | +| **Meta Properties** | Any property | | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 9 | | +|---|---|---| +| **Properties** | capacityGroupID | *Known value* | +| | changedAt | Identical to the most recent of all previously consumed `WeekBasedCapacityGroup` with the same capacityGroupID | +| **Meta Properties** | Any property | | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Overwrite all existing values with consumed values | +| | Return Code | 200 - OK | + +### 4.3 RequestForUpdate API + +The `IdBasedRequestForUpdate` object (RfU) is used to request updates of some or even all `WeekBasedMaterialDemand` or `WeekBasedCapacityGroup` objects. + +Customers and Supplier MUST be able to consume and process a RfU. Being able to provide a RfU is RECOMMENDED. + +To properly proccess a RfU, the following steps MUST be executed: + +1. Response: Answering with the appropriate HTTP status code +2. Action: If that status code is `200 OK`: Providing the requested material demands and capacity groups via `WeekBasedMaterialDemand` API or `WeekBasedCapacityGroup` API respectively. + +It is RECOMMENDED that this functionality SHOULD NOT be an end-user functionality which can be executed in an user interface. + +#### 4.3.1 Preconditions and Dependencies + +The `IdBasedRequestForUpdate` API MUST be published towards the network using a Data Asset/Contract Offer, which is in line with the Dataspace Protocol as specified by IDSA and MUST conform with the Catena-X standard [[CX-0001](#71-normative-references)]. + +#### 4.3.2 API Specification + +##### 4.3.2.1 API endpoints and resources + +The API requires a single endpoint that accepts HTTP POST requests as described in [[RFC9110](#72-non-normative-references)]. The specific structure of the endpoint MAY vary, but its address MUST be included in the Data Asset as defined in [Section 4.1.2.5](#4125-data-asset-structure). + +##### 4.3.2.2 Data exchange + +The `IdBasedRequestForUpdate` data MUST be provided by the customer to the supplier or vice versa via HTTP POST request. The data MUST conform to the format specified in this standard and it MUST NOT exceed 15 MiB in size. +When consuming a payload, that contains unknown properties not described within this standard but is otherwise correct, those properties MUST be ignored. + +An empty RfU payload requests all data within the specific customer-supplier relationship. + +A RfU payload MAY specify that only `WeekBasedMaterialDemand` or `WeekBasedCapacityGroup` objects are requested within the specific customer-supplier relationship. + +A RfU payload MAY specify that only certain data objects, identified by their respective UUID, are requested within the specific customer-supplier relationship. + +A RfU payload MAY specify that only certain data objects, that have been updated, identified by their respective UUID and `changedAt` value, are requested within the specific customer-supplier relationship. + +The following example payloads are intended to illustrate the different possible payloads of an `IdBasedRequestForUpdate`: + +RfU: Provide Everything + +```json +{ +} +``` + +RfU: Provide only Material Demands + +```json +{ + "weekBasedMaterialDemand": [ + ] +} +``` + +RfU: Provide only Capacity Groups + +```json +{ + "weekBasedCapacityGroup": [ + ] +} +``` + +RfU: Provide only certain Objects + +```json +{ + "weekBasedMaterialDemand": [ + { + "materialDemandId":"278e333d-f06b-4b59-8e95-22862f69807f"}, + { + "materialDemandId":"46adfa5d-36b7-4a9b-9ac6-508dac500dd2"} + ] +}, +{ + "weekBasedCapacityGroup": [ + { + "capacityGroupId":"a2fc69ac-ede7-48d3-bee5-04de665d49f0"}, + { + "capacityGroupId":"34238729-990a-4b61-b0c6-336da7b71675"} + ] +} +``` + +RfU: Provide only certain Objects and only if my version is not up to date + +```json +{ + "weekBasedMaterialDemand": [ + { + "materialDemandId":"278e333d-f06b-4b59-8e95-22862f69807f"}, + { + "materialDemandId":"46adfa5d-36b7-4a9b-9ac6-508dac500dd2"} + ] +}, +{ + "weekBasedCapacityGroup": [ + { + "capacityGroupId":"a2fc69ac-ede7-48d3-bee5-04de665d49f0"}, + { + "capacityGroupId":"34238729-990a-4b61-b0c6-336da7b71675", + "changedAt": "2023-03-08T11:44:27.701+01:00"} + ] +} +``` + +##### 4.3.2.3 Available data types + +The API MUST use JSON formatted data transmitted over HTTPS. + +##### 4.3.2.4 Data asset structure + +The HTTP POST endpoint introduced in [Section 4.3.2.1](#4321-api-endpoints-and-resources) MUST NOT be called from a supply chain partner directly. Rather, it MUST be called via a connector conformant to [[CX-0018](#71-normative-references)]. Therefore, the endpoint MUST be offered as a Data Asset. The latter MUST have a property `https://purl.org/dc/terms/type` with the ID `https://w3id.org/catenax/taxonomy#DcmIdBasedRequestForUpdate`. It can be abbreviated if the namespaces of key and value are part of the json-ld @context object (see example below). This property SHOULD be used to identify the asset when searching the assets catalog of a partner. Because the asset reflects the contractual relationship between two DCM partners, only one asset with the aforementioned property for one version MUST be visible to the partner at any time to avoid ambiguity. + +The API version described in this standard MUST be published in the property `https://w3id.org/catenax/ontology/common#version` as version 2.0 in the asset. The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +Each DCM participant MUST ensure that only their business partners have access to the asset by using access and usage policies and respective contract definitions. + +An example Data Asset definition is shown below. + +> Note: Expressions in double curly braces \{\{\}\} MUST be substituted with a corresponding value. +> +> Asset definition example for management API v3 (non-normative) + +```json +{ + "@context": { + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@id": "{{ ASSET_ID }}", + "properties": { + "dct:type": { + "@id": "cx-taxo:DcmIdBasedRequestForUpdate" + }, + "description": "Endpoint for requesting updates", + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ URL-BACKEND-APPLICATION-IDBASEDREQUESTFORUPDATE-ENDPOINT }}", + "method": "POST", + "proxyBody": "true", + "contentType": "application/json" + } +} +``` + +##### 4.3.2.5 Error handling + +Every API endpoint defined in [Section 4.3.2.1](#4321-api-endpoints-and-resources) MUST respond to incoming requests with HTTP status codes as described in [[RFC9110](#72-non-normative-references)]. All of the following HTTP status codes, except for code `200` , MUST be interpreted as failures. Therefore, it may be sufficient for a business application to simply check if the status code is `200` or not. If not, the request failed. + +| HTTP Status Code | HTTP Status Message | Description | +|:-----------------|:--------------------|:-------------| +| 200 | OK | The request has succeeded. The `IdBasedRequestForUpdate` has been successfully processed in the backend system. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | The client request has not been completed because it lacks valid authentication credentials for the requested resource. | +| 403 | Forbidden | The `IdBasedRequestForUpdate` functionality is not available for the client. | +| 405 | Method not allowed | The method used to request the data was not POST. | +| 422 | Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors, e.g. the JSON payload could not be parsed. | +| 503 | Service Unavailable | The client request has not been completed because it lacks valid authentication credentials for the requested resource. | + +Because multiple material demands and capacity groups can be requested at the same time HTTP status code `200` only means that the `IdBasedRequestForUpdate` was processed successfully and that the data objects will be provided in due time. + +The requested data objects SHOULD be provided within five minutes, but definitely they MUST be provided within 24 hours. + +If only a single data object is requested it MUST be provided within 10 seconds. + +##### 4.3.2.6 Validating payload + +Payload validation only applies to the formal layer. If a payload is correctly formed and thusly can be processed HTTP `200` is the correct response code. Even if a material demand (identified by its UUID) has been requested that does not exist within that supplier-customer relationship, HTTP `200` is the correct response code. + +### 4.4 IdBasedComment API + +The `IdBasedComment` object is used to exchange comments, referencing a `WeekBasedCapacityGroup` or a `WeekBasedMaterialDemand` between customer and supplier. + +Customers and suppliers MUST be able to provide, consume and process `IdBasedComment`. + +#### 4.4.1 Preconditions and Dependencies + +The `IdBasedComment` API MUST be published towards the network using a Data Asset/Contract Offer, which is in line with the Dataspace Protocol as specified by IDSA and MUST conform with the Catena-X standard [[CX-0001](#71-normative-references)]. + +#### 4.4.2 API Specification + +##### 4.4.2.1 API endpoints and resources + +The API requires a single endpoint that accepts HTTP POST requests as described in [[RFC9110](#72-non-normative-references)]. The specific structure of the endpoint MAY vary, but its address MUST be included in the Data Asset as defined in [Section 4.1.2.5](#4125-data-asset-structure). + +##### 4.4.2.2 Data exchange + +The `IdBasedComment` data MUST be provided by the customer to the supplier or vice versa via HTTP POST request. The data MUST conform to the format specified in this standard and it MUST NOT exceed 15 MiB in size. It MUST be a valid JSON string and MUST include all mandatory properties. The data model with all its properties MUST conform to the respective aspect model and the definitions in [Chapter 3.4](#34-aspect-model-idbasedcomment). +When consuming a payload, that contains unknown properties not described within the data model but is otherwise correct, those properties MUST be ignored. + +Attributes that are strings MUST be formatted correctly. For example, `expectedSupplierLocation` MUST be formatted as a BPNS. The `listOfReferenceDates` collection MUST represent the calendar week's Mondays in the format YYYY-MM-DD as described in [[ISO8601](#72-non-normative-references)]. + +Certain properties, such as `author`, `objectId`, `listOfReferenceDates` and `objectType`, have specific requirements for their values. `author` MUST contain a valid email address or BPNL if anonymity is preferred. `objectId`, MUST be the UUID of either the `WeekBasedMaterialDemand` or `WeekBasedCapacityGroup` the comments is referencing. `objectType` MUST be as a Catena-X aspect model unique identifier without a version. See [Section 3.1.4](#314-identifier-of-semantic-model) and [Section 3.2.4](#324-identifier-of-semantic-model). + +Multiple `IdBasedComment` aspects MAY be provided in one transfer as a JSON list. If only one `IdBasedComment` aspect is provided, it MUST be as a list with one entry. + +A comment MAY reference more than one calendar week utilizing the `listOfReferenceDates` property. Every entry in `listOfReferenceDates` MUST be set to a Monday, MUST conform to [[ISO8601](#72-non-normative-references)] and MUST use the format YYYY-MM-DD (for example 2023-02-13). + +Applications that consume a `IdBasedComment` with the property `requestDelete` set to `true` MUST delete the comment in compliance with General Data Protection Regulation (GDPR). Deletion is final and MUST NOT be reversed. + +Applications SHOULD remember which comments they originated in order to prevent unauthorized deletion. + +An `IdBasedComment` SHOULD always be provided with as much information as is available, so that the consuming application can better decide how to process the comment. + +The table below MUST be considered in addition to the data model itself and describes which properties MUST be treated as mandatory so that applications can execute certain actions on an `IdBasedComment`. + +| Property \ Action | Create | Update | Delete | +|---|---|---|---| +| **commentId** | MUST | MUST | MUST | +| **objectId** | MUST | MUST | MUST | +| **objectType** | MUST | MUST | MUST | +| **supplier** | MUST | MUST | MUST | +| **customer** | MUST | MUST | MUST | +| commentType | SHOULD - if not, consumer can use value `default` | SHOULD - if not, consumer can use value `default` | MAY | +| author | SHOULD - if not, consumer can use sender BPNL from connector | SHOULD - if not, consumer can use sender BPNL from connector | MAY | +| postedAt | SHOULD - if not, consumer can set timestamp of receipt | SHOULD - MUST NOT differ from time of creation | MAY | +| listOfReferenceDates | MAY | MAY | MAY | +| changedAt | MAY | SHOULD - if not consumer can set timestamp of receipt | MAY | +| commentText | SHOULD | SHOULD | MAY | +| requestDelete | MUST NOT | MUST NOT | MUST | + +##### 4.4.2.3 UUID generation and handling + +UUIDv4 is REQUIRED for exchanging comment data to ensure uniqueness and security. The UUID MUST be generated conforming to [[RFC4122](#72-non-normative-references)] and MUST be treated as unique within the supplier-customer relationship. + +See [Section 4.1.2.7](#4127-validating-payload) for further handling information. + +##### 4.4.2.4 Available data types + +The API MUST use JSON formatted data transmitted over HTTPS. + +##### 4.4.2.5 Data asset structure + +The HTTP POST endpoint introduced in [Section 4.4.2.1](#4421-api-endpoints-and-resources) MUST NOT be called from a supply chain partner directly. Rather, it MUST be called via a connector conformant to [[CX-0018](#71-normative-references)]. Therefore, the endpoint MUST be offered as a Data Asset. The latter MUST have a property `https://purl.org/dc/terms/type` with the ID `https://w3id.org/catenax/taxonomy#DcmIdBasedComment`. It can be abbreviated if the namespaces of key and value are part of the json-ld @context object (see example below). This property SHOULD be used to identify the asset when searching the assets catalog of a partner. Because the asset reflects the contractual relationship between two DCM partners, only one asset with the aforementioned property for one version MUST be visible to the partner at any time to avoid ambiguity. + +The API version described in this standard MUST be published in the property `https://w3id.org/catenax/ontology/common#version` as version 2.0 in the asset. The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +Each DCM participant MUST ensure that only their business partners have access to the asset by using access and usage policies and respective contract definitions. + +An example Data Asset definition is shown below. + +> Note: Expressions in double curly braces \{\{\}\} MUST be substituted with a corresponding value. +> +> Asset definition example for management API v3 (non-normative) + +```json +{ + "@context": { + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@id": "{{ ASSET_ID }}", + "properties": { + "dct:type": { + "@id": "cx-taxo:DcmIdBasedComment" + }, + "description": "Endpoint for providing comments", + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ URL-BACKEND-APPLICATION-IDBASEDCOMMENT-ENDPOINT }}", + "method": "POST", + "proxyBody": "true", + "contentType": "application/json" + } +} +``` + +##### 4.4.2.6 Error handling + +Every API endpoint defined in [Section 4.4.2.1](#4421-api-endpoints-and-resources) MUST respond to incoming requests with HTTP status codes as described in [[RFC9110](#72-non-normative-references)]. All of the following HTTP status codes, except for codes `200` and `201`, MUST be interpreted as failures. Therefore, it may be sufficient for a business application to simply check if the status code is `200` or `202` or not. If not, the request failed. + +| HTTP Status Code | HTTP Status Message | Description | +|:-----------------|:--------------------|:-------------| +| 200 | OK | The request has succeeded. The `IdBasedComment` has been successfully processed in the backend system. | +| 201 | Created | The request has succeeded and has led to the creation of a new `IdBasedComment` in the backend system. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | The client request has not been completed because it lacks valid authentication credentials for the requested resource. | +| 403 | Forbidden | The `IdBasedComment` in question is not available for the client (e.g. it belongs to a different company). | +| 405 | Method not allowed | The method used to request the data was not POST. | +| 422 | Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors, e.g. the JSON payload could not be parsed. | +| 501 | Not Implemented | The `IdBasedComment` is not accepted since the feature is not implemented. | +| 503 | Service Unavailable | The client request has not been completed because it lacks valid authentication credentials for the requested resource. | + +If one `IdBasedComment` aspect is provided in one HTTP request, the return codes MUST be used as stated in the table above. + +If a list of multiple `IdBasedComment` aspects is provided in one HTTP request, the status code `400` MUST be used if at least one `IdBasedComment` in the list cannot be processed. Applications MAY choose to process valid entries from a list which also contains invalid entries. If a list of multiple `IdBasedComment` aspects is provided in one HTTP request and all of them can be processed successfully, the status code 200 MUST be used. + +The return codes `401`, `405`, `422` and `503` in the table above MAY also be applicable to a list of multiple `IdBasedComment` aspects. + +##### 4.4.2.7 Validating payload + +The following tables are supposed to answer questions regarding what business logic MUST be executed when consuming a `IdBasedComment` which has been formed in a specific way. + +The order of rules is indicated by the 'Number' row. + +The first rule that matches MUST be executed. All other rules MUST be ignored. + +'value' indicates the actual value written in quotation marks and without any specific formatting (e.g. italic). + +*Valid value* indicates that the value is valid according to data model, API and process. + +*Invalid value* indicates that the value is invalid according to data model, API and process. + +*Any value* indicates that the value can by anything, valid or not. + +A whitespace or an empty cell indicates that for this specific rule that row is not applicable. + +| **Number** | 1 | | +|---|---|---| +| **Properties** | | | +| **Meta Properties** | Any property | *Invalid value* | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 2 | | +|---|---|---| +| **Properties** | messageHeader.header.senderBpn | Supplier BPNL does not match the sending connectors registered BPNL | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 3 | | +|---|---|---| +| **Properties** | messageHeader.header.senderBpn | Consumer does not match any Partners BPNL that I am in a relation with | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +| **Number** | 4 | | +|---|---|---| +| **Properties** | objectId | Does not match a UUID (`WeekBasedMaterialDemand` or `WeekBasedCapacityGroup`) the consumer exchanged with the provider before | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 403 - Forbidden | + +| **Number** | 5 | | +|---|---|---| +| **Properties** | objectType | Matches the identifier of the `WeekBasedMaterialDemand` (`urn:samm:io.catenax.week_based_material_demand`), but the endpoint does not process an `IdBasedComment` linked to a `WeekBasedMaterialDemand` (compare [Section 5.9.1](#591-detailed-description-of-comments)) | +| **Meta Properties** | Any property | | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 501 - Not Implemented | + +| **Number** | 6 | | +|---|---|---| +| **Properties** | commentId | *Known value* | +| | requestDelete | `true` | +| Meta Properties | Any property | | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Delete comment incl. all of its history from consumers application(s) | +| | Return Code | 200 - OK | + +| **Number** | 7 | | +|---|---|---| +| **Properties** | commentId | *Known value* | +| | changedAt | More recent than all previously consumed `IdBasedComment` with the same commentId | +| **Meta Properties** | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Overwrite all existing values | +| | Return Code | 200 - OK | + +| **Number** | 8 | | +|---|---|---| +| **Properties** | commentId | *Unknown value* | +| Meta Properties | Any property | | +| | All other properties | *Valid value* | +| **Actions** | Business Logic | Save as new comment with consumed values | +| | Return Code | 201 - Created | + +| **Number** | 9 | | +|---|---|---| +| **Properties** | commentId | *Known value* | +| | changedAt | Older than any previously consumed `IdBasedComment` with the same commentId | +| **Meta Properties** | Any property | | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore consumed values | +| | Return Code | 400 - Bad Request | + +### 4.5 DCM Asset Administration Shell API (AAS API) + +Data providers MAY adopt the DCM AAS API. If they choose otherwise, none of the obligations of this section apply. + +The `WeekBasedMaterialDemand` contains the demand information which is provided from the customer to the supplier. The supplier maintains a set of Submodels (one for each `WeekBasedMaterialDemand`) and registers them in their Digital Twin Registry. Both conform to the definitions of [[CX-0002](#71-normative-references)]. + +The `WeekBasedCapacityGroup` contains the capacity information which is provided from the supplier to the customer. The customer maintains a set of Submodels (one for each `WeekBasedCapacityGroup`) and registers them in their Digital Twin Registry. Both conform to the definitions of [[CX-0002](#71-normative-references)]. + +Suppliers MUST be able to host and correctly expose the `WeekBasedMaterialDemand`-Submodel and update the customer-hosted `WeekBasedCapacityGroup`-Submodel. + +Customers MUST be able to host and correctly expose the `WeekBasedCapacityGroup`-Submodel and update the supplier-hosted `WeekBasedMaterialDemand`-Submodel. + +#### 4.5.1 Preconditions and Dependencies + +Not applicable. + +#### 4.5.2 API Specification + +##### 4.5.2.1 API endpoints and resources + +Exchanging Data via the DCM AAS API requires customers and suppliers to both act in the roles of data provider and data consumer. The API is a superset of [[CX-0002](#71-normative-references)] with the following specializations: + +- A supplier MUST host and expose a Submodel `WeekBasedMaterialDemand` via the Submodel-API as defined in [[CX-0002](#71-normative-references)] +- A customer MUST host and expose a Submodel `WeekBasedCapacityGroup` via the Submodel-API as defined in [[CX-0002](#71-normative-references)] +- Additionally, suppliers and customers MUST offer the PatchSubmodel-Operation with the content-modifier `$value` on all Submodels as defined in [[AAS Pt.2](#72-non-normative-references)] + - A supplier MUST client-side be capable to update the `WeekBasedCapacityGroup`-Submodel hosted by the customer + - A customer MUST client-side be capable to update the `WeekBasedMaterialDemand`-Submodel hosted by the supplier + +##### 4.5.2.2 Data exchange + +Restrictions on the exchanged data can be retrieved from the data models. Additionally, the definitions of [Section 4.1.2.2](#4122-data-exchange) and [Section 4.2.2.2](#4222-data-exchange) apply. + +##### 4.5.2.3 UUID generation and handling + +UUIDv4 is REQUIRED for exchanging demand and capacity data to ensure uniqueness and security. The UUID MUST be generated conforming to [[RFC4122](#72-non-normative-references)] and MUST be treated as unique within the supplier-customer relationship. + +See [Section 4.1.2.7](#4127-validating-payload) for further handling information. + +##### 4.5.2.4 Available data types + +The API MUST use JSON formatted data transmitted over HTTPS. + +##### 4.5.2.5 DTR registration + +As mandated by [[CX-0002](#71-normative-references)], all Data-Providers MUST provide a Digital Twin Registry and use it to link their Submodels to identified assets. Assets in the DTR are identified via `specificAssetIds`. + +When registering Submodels with semanticId `WeekBasedMaterialDemand`, the data provider (supplier) MUST reuse the IDs mandated in [[CX-0126](#71-normative-references)], section 2.1.4. + +When registering Submodels with semanticId `WeekBasedCapacityGroup`, the data provider (customer) MUST create a single `specificAssetId` with name `creationEntityId` and a UUIDv4 as value. + +All other properties are standardized in [[CX-0002](#71-normative-references)] or [[AAS Pt.2](#72-non-normative-references)] respectively. + +Example: + +```json +{ + "id": "{{id of the AAS}}", + "idShort": "{{short name of your AAS}}", + "specificAssetIds": [ + { + "name": "creationEntityId", + "value": "{{someUuidV4}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "*" + } + ] + } + } + ], + "submodelDescriptors": [ + { + "id": "{{someSubmodelId}}", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.week_based_capacity_group:2.0.0#WeekBasedCapacityGroup" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "{{dataplane baseurl extended with the appropriate path ending on /submodel}}", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id={{ID of the connector asset the submodel is living behind}};dspEndpoint={{controlPlaneEndpoint}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ] + } + ] +} +``` + +##### 4.5.2.6 Registration + +Obligations for the Asset Definition of the Digital Twin Registry are adopted from [[CX-0002](#71-normative-references)]. + +Obligations for the Asset Definition of a Submodel are adopted from [[CX-0002](#71-normative-references)]. Of the example below, only the "properties"- section is defined as normative there. Please note that the example below only signifies a single registered Submodel. While bundling several Submodels into a single Asset, there are no normative requirements for Asset properties. + +###### 4.5.2.6.1 Data asset + +There are no normative statements on the section `dataAddress` for the Asset. + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#", + "ctx": "https://w3id.org/catenax/taxonomy#", + "aas-semantics": "https://admin-shell.io/aas/3/0/HasSemantics/" + }, + "@id": "{{ID for the Asset}}", + "properties": { + "dct:type": { + "@id": "ctx:Submodel" + }, + "cx-common:version": "3.0", + "aas-semantics:semanticId": "{{URN of WeekBasedMaterialDemand or WeekBasedCapacityGroup Submodel}}" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "proxyPath": "true", + "proxyBody": "true", + "proxyMethod": "true", + "proxyQueryParams": "true", + "baseUrl": "{{Submodel endpoint ending before /submodel}}" + } +} +``` + +###### 4.5.2.6.2 Policy definition + +This policy is an example to let a single business partner pass. It could be used as (part of) either an accessPolicy or contractPolicy. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@type": "PolicyDefinition", + "@id": "{{POLICY-DEFINITION-ID}}", + "policy": { + "odrl:permission": [ + { + "odrl:action": "USE", + "odrl:constraint": [ + { + "odrl:leftOperand": "{{BPN attribute in Data Consumer VC}}", + "odrl:operator": "=", + "odrl:rightOperand": "{{hard-coded BPN of privileged consumer}}" + } + ] + } + ], + "odrl:prohibition": [], + "odrl:obligation": [] + } +} +``` + +###### 4.5.2.6.3 Contract definition + +This example for a contract definition connects the defined policy to the defined asset. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@type": "ContractDefinition", + "@id": "contract-definition-id", + "accessPolicyId": "{{POLICY-DEFINITION-ID}}", + "contractPolicyId": "{{POLICY-DEFINITION-ID}}", + "assetsSelector": [ + { + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "{{ID for the Asset}}" + } + ] +} +``` + +##### 4.5.2.7 Error handling + +Error handling is specified by [[CX-0002](#71-normative-references)] and [[AAS Pt.2](#72-non-normative-references)]. + +## 5 PROCESSES + +> *This section and all its subsections are normative* + +### 5.1 Contextual Description + +The DCM process requires the following steps: + +- Customers provide their material demands +- Suppliers provide their capacities +- Creation of capacity groups which serve as a platform for matching and comparing material demands with supplier capacities + +In addition the following step is optional: + +- Customers and suppliers MAY collaborate by sharing comments + +To facilitate these steps and enable effective collaboration, customers and suppliers in a direct business relationship MUST share data and MUST ensure that shared data is up-to-date. + +All companies participating in Catena-X DCM MUST adopt the common core business logic, data models and data exchange structure described in this standard. + +### 5.2 Actors and Roles + +The DCM core business logic considers three general actors: the customer, the supplier and the business application provider. Note that a single company may have different roles in various business relationships. In fact most companies will have to act as customer and a supplier when considering the whole supply chain network. Regardless of the specific titles within their organizations, all actors have defined responsibilities which are described in [Chapter 1.5](#15-terminology). + +Typical job titles of personnel on the **customer** side: + +- Demand Planner +- Supplier Capacity Manager +- Logistic Planner/Manager +- Buyer + +Typical job titles of personnel on the **supplier** side: + +- Production/Supply Planner +- Demand Planner +- Product Manager +- Sales Manager/Customer Service + +Typical job titles of personnel on the **business application provider** side: + +- Solution/Product Manager +- Developer +- System Architect +- Operations Manager/Responsible +- Support Engineer + +### 5.3 Process Representation + +![Process Chart DCM](./assets/DCM_CoreProcess_SHORT.svg) +*Figure 1: Process Chart DCM* + +For more detailed information, please refer to the Annex [Figures](#figures). + +### 5.4 Prerequisites for a Collaborative Demand and Capacity Management + +Before beginning data exchange, the following conditions MUST be met: + +- Customer and supplier MUST have registered with a Catena-X operational company and conform to the Catena-X guidelines +- Customer and supplier MUST have entered into a contract with each other +- Customer and supplier MUST have signed the DCM framework agreement +- Customer and supplier MUST agree on a common unit of measure (see [Units of measure used in DCM](#units-of-measure-used-in-dcm)) for product-level data exchange (`WeekBasedMaterialDemand` and `WeekBasedCapacityGroup`) +- Customer and supplier MUST have the technical capability to engage in the DCM process with their business applications + +Once these conditions are satisfied, the exchange of demand data and capacity data and fundamental collaboration are enabled. + +### 5.5 Providing Demand Data to Supplier + +#### 5.5.1 Detailed Description of Demand Data + +Customers provide `WeekBasedMaterialDemand` data and any updates to their supplier. + +The supplier MUST be able to consume the `WeekBasedMaterialDemand` from the customer. + +A `WeekBasedMaterialDemand` indicates the need for a specific product or component over a certain time frame and quantity. + +Customers MUST regularly provide their suppliers with `WeekBasedMaterialDemand` data. It is RECOMMENDED to provide the dataset without any gaps, extending at least nine months into the future. + +Customers MAY provide data that extends up to 24 months (or even longer) into the future, as this is considered ideal. + +The `WeekBasedMaterialDemand` data series MAY start from week *n+2* (where n is the current week), although the focus is on mid- to long-term planning (typically 4 to 24 months). + +The customer has the option to mark a `WeekBasedMaterialDemand` as inactive (i.e. the demand is obsolete), in this case the demand will not be considered in the demand-capacity matching. However, the `WeekBasedMaterialDemand` can be reactivated again. + +For technical details see [Section 4.1.2.2](#4122-data-exchange). + +Customers MUST conform to the following guidelines for qualitative demand data and enable an efficient demand and capacity matching: + +- Demand quantities MUST be organized into weekly buckets +- The difference between forecasted demand and actual single-orders SHOULD be minimal +- Demands quantities SHOULD include product phase-ins and/or phase-outs where necessary + +For a detailed process description, see [Figures](#figures). Below is an example of how a `WeekBasedMaterialDemand` might be visualized. + +![Visualized example for Demand Data](./assets/DCM_Example_DemandData.svg) +*Figure 2: Example of Demand Data Visualization* + +- `WeekBasedMaterialDemand` data MUST be categorized as follows: + +| Demand Category | Description | Demand Category Code (based on data model) | +|:----------------|:------------|:-------------------------------------------| +| Default | No Assignment | 0001 | +| After-Sales | After sales demand of spare parts | A1S1 | +| Series | Dependent demand e.g. production, assembly, raw material | SR99 | +| Phase-In-period | Ramp up of a new product or new material introduction | PI01 | +| Single-Order | Demand outside the normal spectrum of supply | OS01 | +| Small series | Short time frame for demand and pose to higher volatility | OI01 | +| Extraordinary demand | Demand on top of standard demand | ED01 | +| Phase-Out-period | Ramp down of a retiring product or material from the market | PO01 | + +- Demand data MUST be consistent with other data exchanged, such as call-offs and updated whenever changes occur + +For implementation details, see [Chapter 3.1](#31-aspect-model-weekbasedmaterialdemand). + +Additional guidelines: + +- Customers SHOULD update demand data at least monthly +- Customers SHOULD avoid or minimize unnecessary fluctuations in demands to allow a better capacity planning, because a stable demand plan enables better capacity planning + +#### 5.5.2 WeekBasedMaterialDemand Structure + +A `WeekBasedMaterialDemand` dataset includes information about the material, the customer-supplier relationship and the requested quantities per week. + +For more information, see [Chapter 3.1](#31-aspect-model-weekbasedmaterialdemand) and [Chapter 4.1](#41-weekbasedmaterialdemand-api). + +If the DCM Asset Administration Shell is used, see [Chapter 4.5](#45-dcm-asset-administration-shell-api-aas-api). + +#### 5.5.3 Example of a Visualization of a WeekBasedMaterialDemand + +The following image shows how `WeekBasedMaterialDemand` information could be visualized, differentiating between **header data** and **time series data**: + +![Visualized example of a material demand structure](./assets/DCM_Example_MD_Structure.svg) +*Figure 3: Visualized example of a material demand structure* + +### 5.6 Providing Capacity Data to Customer + +#### 5.6.1 Detailed Description of Capacity Data + +Suppliers provide `WeekBasedCapacityGroup` data and any updates to their customers. This data MUST refer to the `WeekBasedMaterialDemand` data they previously consumed from their customers. + +The customer MUST be able to consume the `WeekBasedCapacityGroup` from the supplier. + +Suppliers MUST conform to the following guidelines for qualitative capacity data: + +- **Actual capacity** represents the supplier's planned available capacity +- **Maximum capacity** is the highest possible capacity that the supplier can offer, which MAY be equal to or greater than the actual capacity but MUST NOT be less +- **Flexible capacity** is the difference between maximum capacity and actual capacity + +In addition suppliers MAY conform to the following: + +- **Agreed capacity** represents the agreed capacity of a supplier for a specific customer material(s) within a capacity group. It MUST NOT constitute a legal obligation to deliver. Using the agreed capacity is OPTIONAL and has purely informative character. The agreed capacity MAY be greater than, less than or equal to the actual or maximum capacity of the supplier. It MAY be used for a time frame shorter than the whole time series. + +For detailed capacity definitions, see [Chapter 1.5](#15-terminology). + +For a visual process description, see [Figures](#figures). + +#### 5.6.2 WeekBasedCapacityGroup Structure + +A `WeekBasedCapacityGroup` dataset includes information about which material demands it links to, the customer-supplier relationship and how much capacity is available. Thereby providing a shared perspective for both customer and supplier on the matching of demand and capacity information, enables collaborative DCM. + +The `WeekBasedCapacityGroup` can represent combined capacities from machines, facilities, or entire plants. For additional details, especially if using the DCM Asset Administration Shell, see [Chapter 4.5](#45-dcm-asset-administration-shell-api-aas-api). + +For a functional `WeekBasedCapacityGroup`, the supplier MUST link it directly or indirectly to a `WeekBasedMaterialDemand`. + +- Direct linking involves connecting at least one `WeekBasedMaterialDemand` to the `WeekBasedCapacityGroup` +- Indirect linking (or "nesting") involves connecting the `WeekBasedCapacityGroup` to another `WeekBasedCapacityGroup` that is already linked to a `WeekBasedMaterialDemand` + +![Visualized example of possible linkage of WeekBasedMaterialDemand to WeekBasedCapacityGroup](./assets/DCM_Example_CG_Structure.svg) +*Figure 4: Example of Linking `WeekBasedMaterialDemand` to `WeekBasedCapacityGroup`* + +When a supplier provides a `WeekBasedCapacityGroup` to a customer, the following properties MUST have a value so that `WeekBasedCapacityGroup` and `WeekBasedMaterialDemand` can be linked: + +- `supplier` +- `customer` +- `materialNumberCustomer` +- `customerLocation` +- `demandCategory` + +If there's no complete match between supplier and customer data, it's RECOMMENDED to initiate collaboration, as described in [Chapter 5.9](#59-collaboration-functionalities-for-demand-and-capacity-management). + +The supplier has the option to mark a `WeekBasedCapacityGroup` as inactive (i.e. the capacity is obsolete), in this case the capacity will not be considered in the demand-capacity matching. However, the `WeekBasedCapacityGroup` can be reactivated again. + +For more details, see the semantic model in [Chapter 3.2](#32-aspect-model-weekbasedcapacitygroup) and the APIs in [Chapter 4.2](#42-weekbasedcapacitygroup-api). + +#### 5.6.3 Example of a Visualization of Capacity Data + +The figure below demonstrates: + +- The solid line represents actual capacity +- The dotted line represents maximum capacity +- The dashed line represents agreed capacity +- The area between the solid and the dotted lines represents flexible capacity + +![Visualized example of Capacity Data](./assets/DCM_Example_CapacityData.svg) +*Figure 5: Example of Capacity Data Visualization* + +#### 5.6.4 Load Factors for WeekBasedCapacityGroup + +The feature “load factors” allows suppliers to model and represent otherwise impossible capacity occurrences, by introducing a numerical multiplication factor, that changes the interpretation of a capacity group. + +Suppliers MAY apply load factors within a `WeekBasedCapacityGroup`. If they choose to do so, a load factor MUST be applied to every `WeekBasedMaterialDemand` linked by the `WeekBasedCapacityGroup`. + +If a `WeekBasedCapacityGroup` links several `WeekBasedMaterialDemand`, which contain the same material, load factors applied to those `WeekBasedMaterialDemand` SHOULD be identical. + +Load factors SHOULD be used to solve the following two problems: + +- Usage of non-homogeneous material variants within a capacity group, resulting in diverging capacity utilization. +- Requirement for having a different unit of measure within a `WeekBasedCapacityGroup`, as opposed to its linked `WeekBasedMaterialDemand`. + +Load factors solve these problems by: + +- Scaling the weekly demand linearly if a material variant causes higher or lower than normal load within the capacity group. Load factors can for example express a reduction to 90% or an increase to 150%. +- Acting as conversion factors, converting the unit of measure of a `WeekBasedMaterialDemand` into the unit of measure of the `WeekBasedCapacityGroup`. This leads to a conversion into either “time” (unit:secondUnitOfTime) or “cycle” (unit:cycle), expressing that, for example, a piece of material takes 12 seconds or a set of material takes half a cycle to manufacture. + +A load factor of 1 is neutral and leaves the linked `WeekBasedMaterialDemand` unchanged. Because load factors are applied via the `WeekBasedCapacityGroup` a `WeekBasedMaterialDemand` can have multiple load factors applied to it, that differ from each other. Without load factors applied the unit of measure of a `WeekBasedCapacityGroup` and its linked `WeekBasedMaterialDemand` SHOULD be identical. With load factors applied they MAY differ. Lot size restrictions, especially lot size = 1, are not considered when using load factors. Rounding any fractional conversion results SHOULD be avoided to keep demand-capacity comparison consistent. + +### 5.7 Comparison of Demand and Capacity Data within a Capacity Group + +The comparison of aggregated demands and capacities helps to identify imbalances, such as when demand exceeds or falls short of capacity. For visuals, see [Figures](#figures). + +#### 5.7.1 Matching Results and Resolution + +Both customers and suppliers MUST use the same logic when comparing demand and capacity, based on the `WeekBasedCapacityGroup` and `WeekBasedMaterialDemand` models. + +Inactive `WeekBasedMaterialDemand` data and its related `demandSeries` data as well as inactive `WeekBasedCapacityGroup` data MUST NOT be considered when comparing the demand with the corresponding capacity values. + +The table below describes potential scenarios and their outcomes: + +| Scenario and Week | Matching situation (MUST) | Matching result (MUST) | Color (MAY) |Hex Code (MAY)| +|:---------------:|:--------------------------|:----------------------:|:-----------:|:------------:| +| 1 | Demand = actual capacity = maximum capacity | Zero deviation | Green | #809500 | +| 2 | Demand = actual capacity < maximum capacity | Zero deviation | Green | #809500 | +| 3 | Demand < actual capacity = maximum capacity | Surplus | Green | #809500 | +| 4 | Demand < actual capacity < maximum capacity | Surplus | Green | #809500 | +| 5 | Demand > actual capacity = maximum capacity | Bottleneck | Red | #D91E18 | +| 6 | Actual capacity < demand = maximum capacity | Bottleneck | Orange | #FFA600 | +| 7 | Actual capacity < demand < maximum capacity | Bottleneck | Orange | #FFA600 | +| 8 | Actual capacity < maximum capacity < demand | Bottleneck | Red | #D91E18 | + +An example visualization is provided below. + +![Visualized example of Demand and Capacity Data Matching and Comparison](./assets/DCM_Example_MatchAndCompare.svg) +*Figure 6: Visualized example of Demand and Capacity Data Matching and Comparison* + +When a bottleneck or surplus is identified, collaboration between customer and supplier is strongly RECOMMENDED. For more details, see [Figures](#figures). + +The exchange of comments is a key collaborative feature, enabling a dialogue between customers and suppliers. For more information, refer to [Chapter 5.9](#59-collaboration-functionalities-for-demand-and-capacity-management). + +#### 5.7.2 Simulated Delta-Production (Pre-/Post-production) + +##### 5.7.2.1 Business value + +Simulated Delta-Production is a feature that helps suppliers to manage their production capacity more effectively. It allows them to address and balance capacity shortages without having to increase their actual or maximum capacity. Suppliers can choose to use this feature, but it is not mandatory. Simulated Delta-Production, which covers both simulated pre-production and post-production activities. + +The main advantage of using simulated Delta-Production is that it gives suppliers a way to manage small capacity shortfalls. This can be done manually or automatically, which saves time and effort that would otherwise be spent on frequent capacity adjustments, particularly when demand is unpredictable. + +Simulated Delta-Production enables suppliers to add extra detail to their capacity information. This helps illustrate solutions for capacity issues or times when production resources might be offline. Only the end results of simulated Delta-Production are shared with the customer. Suppliers MAY input a simulated Delta-Production value for each week as needed (see Fig. 7 and 8), which shows an increase or decrease in planned demand without actually changing the real figures. + +##### 5.7.2.2 Definition of simulated delta-production (Pre-/post-production) in the context of capacity groups + +Simulated Delta-Production MAY be used within a Capacity Group to indicate how production can be adjusted to meet demand. It helps cover potential shortfalls by showing where goods could be produced earlier or later than currently demanded. Suppliers can provide these simulated values on a weekly basis alongside their regular capacity data. There's no need to give details about the duration of these adjustments, as this can be inferred from the number of weeks for which the simulated data is provided. + +When comparing demand and capacity data, the simulated values are considered without altering the actual data. If a simulated Delta-Production value is provided, it MUST be included in the weekly demand and capacity comparison. A positive value indicates a virtual increase in planned demand, while a negative value indicates a virtual decrease. + +Simulated Delta-Production MUST NOT change the material demand. It's strictly a simulation feature. + +Suppliers can use comments to provide customers with additional information about the simulated Delta-Production. For more details on this communication feature, see [Chapter 5.9](#59-collaboration-functionalities-for-demand-and-capacity-management). + +Below are two examples of how simulated Delta-Production might be represented visually. + +![Visualized example of results of simulated Delta-Production (with pre-production)](./assets/DCM_Example_PreProduction.svg) +*Figure 7: Visualized example of results of simulated Delta-Production (with pre-production)* + +![Visualized example of results of simulated Delta-Production (with post-production)](./assets/DCM_Example_PostProduction.svg) +*Figure 8: Visualized example of results of simulated Delta-Production (with post-production)* + +### 5.8 Request for Update (RfU) + +The Request for Update (RfU) enables customers and suppliers to ask for updates on `WeekBasedMaterialDemand` and `WeekBasedCapacityGroup`. This can be particularly useful to check for and avoid data inconsistency. +Customer and Supplier MUST be capable of consuming and correctly responding to a RfU. Being able to provide a RfU is RECOMMENDED. + +It is RECOMMENDED that this feature is inaccessible to the end-user. + +For further technical information please see [Chapter 3.3](#33-aspect-model-idbasedrequestforupdate) and [Chapter 4.3](#43-requestforupdate-api). + +### 5.9 Collaboration Functionalities for Demand and Capacity Management + +Collaboration is key in DCM. By exchanging comments, customers and suppliers can communicate effectively within their direct business relationships. Comments can be linked to specific data objects, such as material demands or capacity groups and are identified by an unique CommentID. + +This feature benefits users by having all data - even the communication with their business partners - embedded into the core process. This establishes a common point of truth within the DCM process and enables efficient decision making. + +This standard only covers the exchange of textual comments without attachments. It does not describe the visualization, creation, deletion, or internal visibility of comments within an application. + +#### 5.9.1 Detailed Description of Comments + +Customers and suppliers MUST be able to process, provide and consume comments linked to specific objects identified by an `ObjectID`. These objects MUST be a `WeekBasedMaterialDemand` or a `WeekBasedCapacityGroup`. Comments MAY also reference specific time periods to enhance clarity. The exchange of comments MUST conform to standardized data formats and API processing as described in [Chapter 3.4](#34-aspect-model-idbasedcomment) and [Chapter 4.4](#44-idbasedcomment-api). + +Customers and suppliers MUST be able to provide and consume comments linked to `WeekBasedCapacityGroup`. + +Customers and suppliers MUST be able to consume comments linked to `WeekBasedMaterialDemand`. Customers and suppliers SHOULD also be able to process comments linked to `WeekBasedMaterialDemand`. If comments for `WeekBasedMaterialDemand` are not processed by the business logic behind the API a HTTP status code MUST be sent, conforming to [Chapter 4.4](#44-idbasedcomment-api). + +Customers and suppliers SHOULD be able to provide comments linked to `WeekBasedMaterialDemand`. + +Customers and supplier MUST be able to provide and consume a comment deletion. Only the business partner that created the comment MUST be able to update or delete it. If a comment is updated, the `changedAt` timestamp MUST reflect the change. If a comment deletion is being processed successfully the `IdBasedComment` itself, as well as data derived from it, MUST be deleted. + +The table below describes the types of comments that MUST be used: + +| Comment Type | Description | Comment Type Code (based on data model) | +|:-------------|:------------|:----------------------------------------| +| Information comment | Comment purely provides additional information to the exchanged data | `information` | +| Warning comment | Comment provides additional information, which should be considered by the consumer, who might initiate follow up activities | `warning` | +| Action required comment | Consumer of the comment should react on provided information | `actionRequired` | +| Default | Default comment type without special classification | `default` | + +The creator of a comment is responsible for its content and MUST comply with antitrust and information privacy laws. + +### 5.10 Supply Chain Disruption Notifications + +To enable a quick information flow outside a capacity group and the DCM process with regards to upcoming disruptions in the supply chain and potential effect beyond the one-to-one business relationship, a notifications functionality MAY be used. If a business partner decides to use this feature it MUST be used conforming to [[CX–0146](#71-normative-references)]. + +### 5.11 Demand Volatility Metrics + +#### 5.11.1 Business Value + +Demand volatility metric is a feature that helps suppliers to identify and measure demand volatility. It allows them to address demand volatility directly to their customers, increasing transparency for a more effective collaborative capacity planning. + +This standard supports the following volatility metrics: + +- Demand deviation + +#### 5.11.2 Demand Deviation Process + +Customers MUST be able to consume `WeekBasedCapacityGroup`. + +Customers SHOULD be able to fully process `WeekBasedCapacityGroup` that include properties related to demand volatility and calculate the demand deviation metric. If they choose otherwise, none of the obligations of [Chapter 5.11](#511-demand-volatility-metrics) apply. + +Suppliers MUST process and provide `WeekBasedCapacityGroup`. + +Suppliers SHOULD process and provide `WeekBasedCapacityGroup` that include properties related to demand volatility and calculate the demand deviation metric. If they choose to use this feature at least `startReferenceDateTime` and `measurementInterval` must be provided. If they choose otherwise, none of the obligations of [Chapter 5.11](#511-demand-volatility-metrics) apply. + +After suppliers identify critical `WeekBasedCapacityGroup` and apply demand deviation metrics to them the following applies: + +- Suppliers and customers MUST calculate the demand deviation metric exactly as described in [Section 5.11.3](#5113-demand-deviation-metric). Other calculation methods MUST NOT be used for the calculation of the metric. +- Suppliers MUST calculate the demand deviation metric on `WeekBasedCapacityGroup` level. +- Suppliers MUST activate each of the `WeekBasedCapacityGroups` for which the metric has to be calculated, see [Chapter 4.2](#42-weekbasedcapacitygroup-api). +- Suppliers MUST specify the start date of calculations at a future date and time. The first calculation will then be completed at the end of the first measurement interval, see [Chapter 4.2](#42-weekbasedcapacitygroup-api). +- If suppliers change the measurement interval, they MUST specify a new start date of calculations at a future date and time. +- Suppliers SHOULD NOT calculate the demand deviation based on any data measured before the start date of calculations. +- Suppliers MUST provide the parameters of the calculation of the demand deviation metric to their customers, as specified in [Section 5.11.3](#5113-demand-deviation-metric) and [Chapter 4.2](#42-weekbasedcapacitygroup-api). +- Suppliers SHOULD compare the results of the calculation of the demand deviation metric to the relevant alert thresholds defined for the demand deviation metric, see [Section 5.11.3](#5113-demand-deviation-metric). + +The demand deviation is calculated locally and compared against the consumed or provided values from the `WeekBasedCapacityGroup`. The table below describes potential scenarios and their outcomes: + +| Scenario and Week | Matching situation (MUST) | Matching result (MUST) | Color (MAY) |Hex Code (MAY)| +|:---------------:|:--------------------------|:----------------------:|:-----------:|:------------:| +| 1 | Calculated relative demand deviation > `relativePositiveDeviation` | Unacceptable deviation | Red | #D91E18 | +| 2 | Calculated relative demand deviation < `relativeNegativeDeviation` | Unacceptable deviation | Red | #D91E18 | +| 3 | Calculated absolute demand deviation > `absolutePositiveDeviation` | Unacceptable deviation | Red | #D91E18 | +| 4 | Calculated absolute demand deviation < `absoluteNegativeDeviation` | Unacceptable deviation | Red | #D91E18 | + +![Visualized Example of Demand Deviation and Alert Threshold Comparison](./assets/DCM_Example_DemandDeviationAndAlertThreshold.svg) +*Figure 9: Visualized example of Demand Deviation and Alert Threshold Comparison* + +It is RECOMMENDED that suppliers organize individual collaborative alignments with customers to discuss the status of significant volatility measurements of demand deviation, ideally at least on a quarterly basis. + +The exchange of comments is a key collaborative feature, enabling a dialogue between customers and suppliers. For details, see [Chapter 5.9](#59-collaboration-functionalities-for-demand-and-capacity-management). + +#### 5.11.3 Demand Deviation Metric + +The demand deviation metric is generally based on the comparison of the latest demand with a previous demand. It is RECOMMENDED to compare the latest demand with previous demands on a monthly basis, in line with typical monthly long-term planning cycles and set the measurement interval to 4 weeks. + +The demand deviation metric is calculated at the `WeekBasedCapacityGroup` level, meaning the demands of 1..n material demand series assigned to a specific `WeekBasedCapacityGroup` are aggregated on a weekly level and form the basis for the calculation. Thus, the time series of aggregated material demands which is measured at a defined point in time in the current week is equal to the latest demand. The time series of aggregated material demands which is measured at a defined point in time in an earlier week is equal to the previous demand. + +Suppliers initiate the calculation of the demand deviation metric by specifying the start date of the calculation `StartReferenceDateTime` at a future date and time. This marks the point in time of the first measurement of the aggregated material demand. The date and time of subsequent measurements is defined by the measurement interval that also describes the time offset in weeks between the latest demand time series and the previous demand time series. + +**Calculation** + +The demand deviation MUST be calculated as follows: + +$$Absolute Deviation =\sum Latest Demand - \sum Previous Demand$$ + +$$Relative Deviation = \frac\{\sum Latest Demand - \sum Previous Demand\}\{\sum Previous Demand\}$$ + +∑ ≙ sum of demands per calendar week of each material demand series assigned within the `WeekBasedCapacityGroup`. + +![Visualized Example of Demand Deviation Calculation at Capacity Group Level](./assets/DCM_Example_DemandDeviationCalculation.svg) +*Figure 10: Visualized example of demand deviation calculation at capacity group level* + +It is RECOMMENDED to store the inputs for the calculations of the demand deviation metric for at least 6 months. + +**Alert Threshold** + +Alert thresholds are positive or negative values of demand deviation that define unacceptable levels of demand volatility with reference to a specific subhorizon. + +Suppliers SHOULD specify values for at least one of the following two alert thresholds: + +- Maximum relative positive deviation: (e.g. max. 15 % quantity increase compared to previous demand) + - ∆rel. pos. MUST be ≥ 0 (1 ≙ 100%) +- Maximum relative negative deviation: (e.g. max. 10 % quantity decrease compared to previous demand) + - ∆rel. neg. MUST be ≥ 0 and ≤ 1 (1 ≙ -100%) + +To cover more business scenarios, suppliers MAY specify values for the following two alert thresholds: + +- Maximum absolute positive deviation: (e.g. max. 1000 units more compared to previous demand) + - ∆abs. pos. +- Maximum absolute negative deviation: (e.g. max. 500 units less compared to previous demand) + - ∆abs. neg. + +Threshold values cannot be standardized across the Catena-X network, but must be individually agreed and made transparent between two business partners. + +**Subhorizons** + +A subhorizon is a period of time that represents a part of the whole DCM time frame and is used for a specific view on the calculation of the demand deviation metric. Suppliers MAY specify subhorizons to allow for different alert thresholds, as the flexibility of supply chains decreases, the closer demand values approach today's date. It is RECOMMENDED to divide the rolling DCM time frame (typically up to 104 weeks) into multiple subhorizons. + +A subhorizon is defined as follows: + +For 1,2,3,...h subhorizons (1 ≤ h ≤ 104): + +- Subhorizon length l (1 ≤ l ≤ 104, l = number of weeks) +- Subhorizon alert thresholds: one value for each alert threshold to be used within the subhorizon + +The start and end of a subhorizon are determined as follows: + +- Subhorizon start = week 0 for the first subhorizon OR subhorizon end of the previous subhorizon + 1 +- Subhorizon end = subhorizon start + subhorizon length l + +It is RECOMMENDED to apply the following rules: + +- The subhorizons are sequenced consecutively (1,2,3,...). +- The sequence starts always with 1. +- The first week of the first subhorizon is denominated as week 0. +- There are no gaps in between the subhorizons, they are always consecutive. +- The entire DCM time frame (104 weeks) does not need to be fully populated with subhorizons. +- In case a subhorizon does not contain any deviation properties, no alert threshold is applicable. + +![Visualized example of Demand Deviation subhorizons](./assets/DCM_Example_DemandDeviationSubHorizons.svg) +*Figure 11: Visualized example of Demand Deviation subhorizons and related alert thresholds* + +## 6 FRAMEWORK AGREEMENT AND POLICIES + +> *This section and all its subsections are normative* + +All participants involved in the Catena-X DCM use case MUST consent to the DCM framework agreement. + +A key aspect of managing business partner relationships within Catena-X involves defining and applying policies that facilitate and protect data exchange. Both customers and suppliers MUST implement and uphold these policies in order to guarantee a secure and collaborative data exchange: + +| Category | Policy Name | Description | +|:---------|:------------|:------------| +| **Access Policy** | BPN-restricted Data Usage | Limit access to the data offered to a list of specified BPNs (to the connectors with the BPN attribute listed in the policy) | +| **Access Policy** | Membership Credential | Limit access to data offered to Catena-X participants | +| **Usage Policy** | DCM Framework Agreement Credential | Limit access to data offered to participants who have signed the DCM Framework Agreement | + +## 7 REFERENCES + +### 7.1 Normative References + +> *This section and all its subsections are normative* + +[CX-0001] `v1.0.2` EDC Discovery API + +[CX-0002] `v2.2.0` Digital Twins in Catena-X + +[CX-0003] `v1.1.0` SAMM Aspect Meta Model + +[CX-0010] `v2.0.0` Business Partner Number + +[CX-0018] `v3.0.0` Dataspace Connectivity + +[CX-0126] `v2.0.0` Industry Core: Part Type + +[CX-0146] `v1.0.0` Supply Chain Disruption Notifications + +### 7.2 Non-Normative References + +> *This section and all its subsections are non-normative* + +[RFC2119] `March 1997` Key words for use in RFCs to Indicate Requirement Levels (https://www.rfc-editor.org/rfc/rfc2119) + +[RFC8174] `May 2017` Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words (https://www.rfc-editor.org/rfc/rfc8174) + +[ISO3166] `2020-08` ISO 3166 Country Codes + +[ISO8601] `2019-02` Date and time format + +[RFC4122] `July 2005` A Universally Unique IDentifier (UUID) URN Namespace (https://www.rfc-editor.org/rfc/rfc4122) + +[RFC9110] `June 2022` HTTP Semantics (https://www.rfc-editor.org/rfc/rfc9110) + +[CC-BY-4.0] `Version 4.0` Creative Commons Attribution 4.0 International license (https://creativecommons.org/licenses/by/4.0/legalcode.en) + +[SMT] `1st Version` Guideline: How to create a Submodel template specification (https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf) + +[I4.0-AAS] `1.0RC02` Details of the Asset Administration Shell - Part 2 (https://www.plattform-i40.de/IP/Redaktion/EN/Downloads/Publikation/Details_of_the_Asset_Administration_Shell_Part2_V1.html) + +### 7.3 Reference Implementations + +> *This section and all its subsections are non-normative* + +Not applicable. + +## ANNEXES + +> *This section and all its subsections are non-normative* + +### Figures + +Below are illustrative figures that depict the DCM process from the viewpoints of customers and suppliers. + +![Complete DCM process](./assets/DCM_CoreProcess_BPMN.svg) +*Figure 12: Complete DCM process* + +![Complete DCM process with digital twins](./assets/DCM_CoreProcess_with_Twins_BPMN.svg) +*Figure 13: Complete DCM process with digital twins* + +### Tables + +#### Units of measure used in DCM + +| Dimension | UN Code | Description (English) | Description (German) | UN Symbol | C-X Symbol | Reference unit used in data models | +|:----------|--------:|:----------------------|:---------------------|----------:|-----------:|:-----------------------------------| +| Mass | GRM | gram | Gramm | g | g | unit:gram | +| Mass | KGM | kilogram | Kilogramm | kg | kg | unit:kilogram | +| Mass | TNE | metric ton | Metrische Tonne | t | t | unit:tonneMetricTon | +| Mass | STN | ton (US) or short ton (UK/US) | US Tonne | ton (US) | ton | unit:tonUsOrShortTonUkorus | +| Mass | ONZ | ounce | Unze | oz | oz | unit:ounceAvoirdupois | +| Mass | LBR | pound | Pfund | lb | lb | unit:pound | +| Length | CMT | centimetre | Zentimeter | cm | cm | unit:centimetre | +| Length | MTR | metre | Meter | m | m | unit:metre | +| Length | KTM | kilometre | Kilometer | km | km | unit:kilometre | +| Length | INH | inch | Zoll | in | in | unit:inch | +| Length | FOT | foot | Fuß | ft | ft | unit:foot | +| Length | YRD | yard | Yard | yd | yd | unit:yard | +| Area | CMK | square centimetre | Quadrat-zentimeter | cm2 | cm2 | unit:squareCentimetre | +| Area | MTK | square metre | Quadratmeter | m2 | m2 | unit:squareMetre | +| Area | INK | square inch | Quadratzoll | in2 | in2 | unit:squareInch | +| Area | FTK | square foot | Quadratfuß | ft2 | ft2 | unit:squareFoot | +| Area | YDK | square yard | Quadratyard | yd2 | yd2 | unit:squareYard | +| Volume | CMQ | cubic centimeter | Kubikzentimeter | cm3 | cm3 | unit:cubicCentimetre | +| Volume | MTQ | cubic meter | Kubikmeter | m3 | m3 | unit:cubicMetre | +| Volume | INQ | cubic inch | Kubikzoll | in3 | in3 | unit:cubicInch | +| Volume | FTQ | cubic foot | Kubikfuß | ft3 | ft3 | unit:cubicFoot | +| Volume | YDQ | cubic yard | Kubikyard | yd3 | yd3 | unit:cubicYard | +| Volume | MLT | millilitrev | Millimeter | ml | ml | unit:millilitre | +| Volume | LTR | litre | Liter | l | l | unit:litre | +| Volume | HLT | hectolitre | Hektoliter | hl | hl | unit:hectolitre | +| Quantum | H87 | piece | Stück | - | pc | unit:piece | +| Quantum | SET | set | Satz | - | set | unit:set | +| Quantum | PR | pair | Paar | - | pr | unit:pair | +| Quantum | ZP | page | Blatt | - | pg | unit:page | +| Mechanic | KWH | kilowatt hour | Kilowattstunde | kW·h | kwh | unit:kilowattHour | +| Time | SEC | second [unit of time] | Sekunde [Maßeinheit der Zeit] | s | s | unit:secondUnitOfTime | +| Time | MIN | minute [unit of time] | Minute [Maßeinheit der Zeit] | min | min | unit:minuteUnitOfTime | +| Time | HUR | hour | Stunde | h | h | unit:hourUnitOfTime | +| Cycle | B7 | cycle | Zyklus | [empty] | cyl | unit:cycle | + +### Repositories + +[ODRL] ODRL policy repository (https://github.com/catenax-eV/cx-odrl-profile) + +## ABOUT THIS STANDARD AND MOTIVATION + +> *This section and all its subsections are non-normative* + +## DISCLAIMER AND LIABILITY + +> *This section and all its subsections are non-normative* + +## REVISIONS AND UPDATE + +> *This section and all its subsections are non-normative* + +## COPYRIGHT AND TRADEMARKS + +> *This section and all its subsections are non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_CoreProcess_BPMN.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_CoreProcess_BPMN.svg new file mode 100644 index 000000000..721508c30 --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_CoreProcess_BPMN.svg @@ -0,0 +1,6748 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zeichenblatt-1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CFF-Container.17 + + Tabelle.18 + + + + + + + + + + + + + Tabelle.19 + Titel + + + + + + + + + + + + + + + + + + + + + + + Verantwortlichkeitsbereichsliste.20 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CFF Container.102 + + Tabelle.103 + + + + + + + + + + + + + Tabelle.104 + Titel + + + + + + + + + + + + + + + + + + + + + + + Swimlane List.105 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Pool/Verantwortlichkeitsbereich.13 + + Tabelle.14 + + + + + + + + + + + + + + Tabelle.15 + + + + + + Tabelle.16 + Supplier + + + + + + + + + + + + + + + + + + + Supplier + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Pool / Lane.106 + + Tabelle.107 + + + + + + + + + + + + + + Tabelle.108 + + + + + + Tabelle.109 + Customer + + + + + + + + + + + + + + + + + + + Customer + + + Phasenliste.21 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Trennzeichen.22 + + Tabelle.23 + + + + + + + Tabelle.24 + Phase + + + + + + + + + + + + + + + + + + Phase List.110 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Separator.111 + + Tabelle.112 + + + + + + + Tabelle.113 + Phase + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Start Event + Start + + Tabelle.27 + + + + + + + Tabelle.28 + + + + Tabelle.29 + + + + Tabelle.30 + + + + Tabelle.31 + + + Tabelle.32 + + + Tabelle.33 + + + Tabelle.34 + + + Tabelle.35 + + + Tabelle.36 + + + Tabelle.37 + + + Tabelle.38 + + + + + Start + + + + + + + + + + + + + + + + + + + + + + + + + + + Start Event.114 + Start + + Tabelle.115 + + + + + + + Tabelle.116 + + + + Tabelle.117 + + + + Tabelle.118 + + + + Tabelle.119 + + + Tabelle.120 + + + Tabelle.121 + + + Tabelle.122 + + + Tabelle.123 + + + Tabelle.124 + + + Tabelle.125 + + + Tabelle.126 + + + + + Start + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Reduzierter Teilprozess + Demand Calculation + + Tabelle.294 + + + + Tabelle.295 + + Tabelle.296 + + + + Tabelle.297 + + + + + Tabelle.298 + + + + + + + + + + + Tabelle.299 + + Tabelle.300 + + + + + Tabelle.301 + + + + + Tabelle.302 + + + + + + + Tabelle.303 + + + + + + + + + + + Tabelle.304 + + Tabelle.305 + + + + Tabelle.306 + + + Tabelle.307 + + + Tabelle.308 + + Tabelle.309 + + + + Tabelle.310 + + + + Tabelle.311 + + + Tabelle.312 + + + Tabelle.313 + + + Tabelle.314 + + + Tabelle.315 + + + + + + + + + Demand Calculation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe + Aggregate demand data as weekly buckets + + Tabelle.317 + + + + Tabelle.318 + + Tabelle.319 + + + + Tabelle.320 + + + + + Tabelle.321 + + + + + + + + + + + Tabelle.322 + + Tabelle.323 + + + + Tabelle.324 + + + + Tabelle.325 + + + + + + + Tabelle.326 + + + + + + + + + + + Tabelle.327 + + Tabelle.328 + + + + Tabelle.329 + + + Tabelle.330 + + + Tabelle.331 + + Tabelle.332 + + + + Tabelle.333 + + + + Tabelle.334 + + + Tabelle.335 + + + Tabelle.336 + + + Tabelle.337 + + + Tabelle.338 + + + + + + + + + Aggregate demand data as weekly buckets + + + Sequenzfluss + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.340 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Datenobjekt + Material Demand + + Tabelle.343 + + + + Tabelle.344 + + + + + Material Demand + + + Assoziation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.346 + Identify relevant material numbers + + Tabelle.347 + + + + Tabelle.348 + + Tabelle.349 + + + + Tabelle.350 + + + + + Tabelle.351 + + + + + + + + + + + Tabelle.352 + + Tabelle.353 + + + + Tabelle.354 + + + + Tabelle.355 + + + + + + + Tabelle.356 + + + + + + + + + + + Tabelle.357 + + Tabelle.358 + + + + Tabelle.359 + + + Tabelle.360 + + + Tabelle.361 + + Tabelle.362 + + + + Tabelle.363 + + + + Tabelle.364 + + + Tabelle.365 + + + Tabelle.366 + + + Tabelle.367 + + + Tabelle.368 + + + + + + + + + Identify relevant material numbers + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis + Material Demand + + Tabelle.370 + + + + + + + Tabelle.371 + + + + Tabelle.372 + + + + Tabelle.373 + + + + Tabelle.374 + + + + + + + Tabelle.375 + + + Tabelle.376 + + + Tabelle.377 + + + Tabelle.378 + + + Tabelle.379 + + + Tabelle.380 + + + Tabelle.381 + + + + + Material Demand + + + Nachrichtenfluss + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss.383 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.384 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.385 + Create Capacity Group + + Tabelle.386 + + + + Tabelle.387 + + Tabelle.388 + + + + Tabelle.389 + + + + + Tabelle.390 + + + + + + + + + + + Tabelle.391 + + Tabelle.392 + + + + Tabelle.393 + + + + Tabelle.394 + + + + + + + Tabelle.395 + + + + + + + + + + + Tabelle.396 + + Tabelle.397 + + + + Tabelle.398 + + + Tabelle.399 + + + Tabelle.400 + + Tabelle.401 + + + + Tabelle.402 + + + + Tabelle.403 + + + Tabelle.404 + + + Tabelle.405 + + + Tabelle.406 + + + Tabelle.407 + + + + + + + + + Create Capacity Group + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.408 + Link Material Demand to Capacity Group + + Tabelle.409 + + + + Tabelle.410 + + Tabelle.411 + + + + Tabelle.412 + + + + + Tabelle.413 + + + + + + + + + + + Tabelle.414 + + Tabelle.415 + + + + Tabelle.416 + + + + Tabelle.417 + + + + + + + Tabelle.418 + + + + + + + + + + + Tabelle.419 + + Tabelle.420 + + + + Tabelle.421 + + + Tabelle.422 + + + Tabelle.423 + + Tabelle.424 + + + + Tabelle.425 + + + + Tabelle.426 + + + Tabelle.427 + + + Tabelle.428 + + + Tabelle.429 + + + Tabelle.430 + + + + + + + + + Link Material Demand to Capacity Group + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.431 + Aggregate capacity data as weekly buckets + + Tabelle.432 + + + + Tabelle.433 + + Tabelle.434 + + + + Tabelle.435 + + + + + Tabelle.436 + + + + + + + + + + + Tabelle.437 + + Tabelle.438 + + + + Tabelle.439 + + + + Tabelle.440 + + + + + + + Tabelle.441 + + + + + + + + + + + Tabelle.442 + + Tabelle.443 + + + + Tabelle.444 + + + Tabelle.445 + + + Tabelle.446 + + Tabelle.447 + + + + Tabelle.448 + + + + Tabelle.449 + + + Tabelle.450 + + + Tabelle.451 + + + Tabelle.452 + + + Tabelle.453 + + + + + + + + + Aggregate capacity data as weekly buckets + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.454 + Finalize and send Capacity Group + + Tabelle.455 + + + + Tabelle.456 + + Tabelle.457 + + + + Tabelle.458 + + + + + Tabelle.459 + + + + + + + + + + + Tabelle.460 + + Tabelle.461 + + + + Tabelle.462 + + + + Tabelle.463 + + + + + + + Tabelle.464 + + + + + + + + + + + Tabelle.465 + + Tabelle.466 + + + + Tabelle.467 + + + Tabelle.468 + + + Tabelle.469 + + Tabelle.470 + + + + Tabelle.471 + + + + Tabelle.472 + + + Tabelle.473 + + + Tabelle.474 + + + Tabelle.475 + + + Tabelle.476 + + + + + + + + + Finalize and send Capacity Group + + + Sequenzfluss.477 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.482 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Datenobjekt.492 + Capacity Group + + Tabelle.493 + + + + Tabelle.494 + + + + + Capacity Group + + + Assoziation.495 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Assoziation.496 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Assoziation.515 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Assoziation.516 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss.517 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.541 + Capacity Group + + Tabelle.542 + + + + + + + Tabelle.543 + + + + Tabelle.544 + + + + Tabelle.545 + + + + Tabelle.546 + + + + + + + Tabelle.547 + + + Tabelle.548 + + + Tabelle.549 + + + Tabelle.550 + + + Tabelle.551 + + + Tabelle.552 + + + Tabelle.553 + + + + + Capacity Group + + + Sequenzfluss.555 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.556 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.557 + Analyze Capacity Group + + Tabelle.558 + + + + Tabelle.559 + + Tabelle.560 + + + + Tabelle.561 + + + + + Tabelle.562 + + + + + + + + + + + Tabelle.563 + + Tabelle.564 + + + + Tabelle.565 + + + + Tabelle.566 + + + + + + + Tabelle.567 + + + + + + + + + + + Tabelle.568 + + Tabelle.569 + + + + Tabelle.570 + + + Tabelle.571 + + + Tabelle.572 + + Tabelle.573 + + + + Tabelle.574 + + + + Tabelle.575 + + + Tabelle.576 + + + Tabelle.577 + + + Tabelle.578 + + + Tabelle.579 + + + + + + + + + Analyze Capacity Group + + + Sequenzfluss.580 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gateway + + Tabelle.605 + + + + Tabelle.606 + + + + Tabelle.607 + + Tabelle.608 + + + Tabelle.609 + + + + Tabelle.610 + + + Tabelle.611 + + + Tabelle.612 + + + Tabelle.613 + + Tabelle.614 + + + + Tabelle.615 + + + + Tabelle.616 + + Tabelle.617 + + + + Tabelle.618 + + + + + Sequenzfluss.619 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Endereignis.15 + + Tabelle.680 + + + + + + + Tabelle.681 + + + + Tabelle.682 + + + + Tabelle.683 + + + + Tabelle.684 + + + Tabelle.685 + + + Tabelle.686 + + + Tabelle.687 + + + Tabelle.688 + + + Tabelle.689 + + + Tabelle.690 + + + Tabelle.691 + + + + + Sequenzfluss.692 + Exact match + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Exactmatch + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.693 + + Tabelle.694 + + + + + + + + Tabelle.695 + + + + Tabelle.696 + + + + Tabelle.697 + + + + Tabelle.698 + + + Tabelle.699 + + + Tabelle.700 + + + Tabelle.701 + + + Tabelle.702 + + + Tabelle.703 + + + Tabelle.704 + + + Tabelle.705 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.706 + + Tabelle.707 + + + + + + + + Tabelle.708 + + + + Tabelle.709 + + + + Tabelle.710 + + + + Tabelle.711 + + + Tabelle.712 + + + Tabelle.713 + + + Tabelle.714 + + + Tabelle.715 + + + Tabelle.716 + + + Tabelle.717 + + + Tabelle.718 + + + + + Sequenzfluss.719 + Deficit + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Deficit + + Sequenzfluss.720 + Surplus + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surplus + + + + + + + + + + + + + + + + + + + + + + Gateway.721 + + Tabelle.722 + + + + Tabelle.723 + + + + Tabelle.724 + + Tabelle.725 + + + Tabelle.726 + + + + Tabelle.727 + + + Tabelle.728 + + + Tabelle.729 + + + Tabelle.730 + + Tabelle.731 + + + + Tabelle.732 + + + + Tabelle.733 + + Tabelle.734 + + + + Tabelle.735 + + + + + Sequenzfluss.736 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.737 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.781 + Align capacties and demands + + Tabelle.782 + + + + Tabelle.783 + + Tabelle.784 + + + + Tabelle.785 + + + + + Tabelle.786 + + + + + + + + + + + Tabelle.787 + + Tabelle.788 + + + + Tabelle.789 + + + + Tabelle.790 + + + + + + + Tabelle.791 + + + + + + + + + + + Tabelle.792 + + Tabelle.793 + + + + Tabelle.794 + + + Tabelle.795 + + + Tabelle.796 + + Tabelle.797 + + + + Tabelle.798 + + + + Tabelle.799 + + + Tabelle.800 + + + Tabelle.801 + + + Tabelle.802 + + + Tabelle.803 + + + + + + + + + Align capacties and demands + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.804 + Align capacties and demands + + Tabelle.805 + + + + Tabelle.806 + + Tabelle.807 + + + + Tabelle.808 + + + + + Tabelle.809 + + + + + + + + + + + Tabelle.810 + + Tabelle.811 + + + + Tabelle.812 + + + + Tabelle.813 + + + + + + + Tabelle.814 + + + + + + + + + + + Tabelle.815 + + Tabelle.816 + + + + Tabelle.817 + + + Tabelle.818 + + + Tabelle.819 + + Tabelle.820 + + + + Tabelle.821 + + + + Tabelle.822 + + + Tabelle.823 + + + Tabelle.824 + + + Tabelle.825 + + + Tabelle.826 + + + + + + + + + Align capacties and demands + + + Nachrichtenfluss.831 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss.832 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gateway.880 + + Tabelle.881 + + + + Tabelle.882 + + + Tabelle.883 + + Tabelle.884 + + + Tabelle.885 + + + + Tabelle.886 + + + + Tabelle.887 + + + Tabelle.888 + + + Tabelle.889 + + Tabelle.890 + + + + Tabelle.891 + + + + Tabelle.892 + + Tabelle.893 + + + + Tabelle.894 + + + + + Sequenzfluss.895 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.896 + Update capacities in Capacity Group + + Tabelle.897 + + + + Tabelle.898 + + Tabelle.899 + + + + Tabelle.900 + + + + + Tabelle.901 + + + + + + + + + + + Tabelle.902 + + Tabelle.903 + + + + Tabelle.904 + + + + Tabelle.905 + + + + + + + Tabelle.906 + + + + + + + + + + + Tabelle.907 + + Tabelle.908 + + + + Tabelle.909 + + + Tabelle.910 + + + Tabelle.911 + + Tabelle.912 + + + + Tabelle.913 + + + + Tabelle.914 + + + Tabelle.915 + + + Tabelle.916 + + + Tabelle.917 + + + Tabelle.918 + + + + + + + + + Update capacities in Capacity Group + + + Sequenzfluss.919 + Alignment by capacity adjustment + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Alignment by capacity adjustment + + Assoziation.920 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.945 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.947 + Update demands linked in Capacity Group + + Tabelle.948 + + + + Tabelle.949 + + Tabelle.950 + + + + Tabelle.951 + + + + + Tabelle.952 + + + + + + + + + + + Tabelle.953 + + Tabelle.954 + + + + Tabelle.955 + + + + Tabelle.956 + + + + + + + Tabelle.957 + + + + + + + + + + + Tabelle.958 + + Tabelle.959 + + + + Tabelle.960 + + + Tabelle.961 + + + Tabelle.962 + + Tabelle.963 + + + + Tabelle.964 + + + + Tabelle.965 + + + Tabelle.966 + + + Tabelle.967 + + + Tabelle.968 + + + Tabelle.969 + + + + + + + + + Update demands linked in Capacity Group + + + Sequenzfluss.970 + Alignment by demand adjustment + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Alignment by demand adjustment + + + + + + + + + + + + + + + + + + + + + + + + Gateway.971 + + Tabelle.972 + + + + Tabelle.973 + + + Tabelle.974 + + Tabelle.975 + + + Tabelle.976 + + + + Tabelle.977 + + + + Tabelle.978 + + + Tabelle.979 + + + Tabelle.980 + + Tabelle.981 + + + + Tabelle.982 + + + + Tabelle.983 + + Tabelle.984 + + + + Tabelle.985 + + + + + Sequenzfluss.986 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.987 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.1037 + Update demands + + Tabelle.1038 + + + + + + + Tabelle.1039 + + + + Tabelle.1040 + + + + Tabelle.1041 + + + + Tabelle.1042 + + + + + + + Tabelle.1043 + + + Tabelle.1044 + + + Tabelle.1045 + + + Tabelle.1046 + + + Tabelle.1047 + + + Tabelle.1048 + + + Tabelle.1049 + + + + + Update demands + + + Nachrichtenfluss.1050 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1051 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1121 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1122 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.1147 + Analyze Capacity Group + + Tabelle.1148 + + + + Tabelle.1149 + + Tabelle.1150 + + + + Tabelle.1151 + + + + + Tabelle.1152 + + + + + + + + + + + Tabelle.1153 + + Tabelle.1154 + + + + Tabelle.1155 + + + + Tabelle.1156 + + + + + + + Tabelle.1157 + + + + + + + + + + + Tabelle.1158 + + Tabelle.1159 + + + + Tabelle.1160 + + + Tabelle.1161 + + + Tabelle.1162 + + Tabelle.1163 + + + + Tabelle.1164 + + + + Tabelle.1165 + + + Tabelle.1166 + + + Tabelle.1167 + + + Tabelle.1168 + + + Tabelle.1169 + + + + + + + + + Analyze Capacity Group + + + + + + + + + + + + + + + + + + + + + + + Gateway.1170 + + Tabelle.1171 + + + + Tabelle.1172 + + + + Tabelle.1173 + + Tabelle.1174 + + + Tabelle.1175 + + + + Tabelle.1176 + + + Tabelle.1177 + + + Tabelle.1178 + + + Tabelle.1179 + + Tabelle.1180 + + + + Tabelle.1181 + + + + Tabelle.1182 + + Tabelle.1183 + + + + Tabelle.1184 + + + + + Sequenzfluss.1185 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Endereignis.1186 + + Tabelle.1187 + + + + + + + Tabelle.1188 + + + + Tabelle.1189 + + + + Tabelle.1190 + + + + Tabelle.1191 + + + Tabelle.1192 + + + Tabelle.1193 + + + Tabelle.1194 + + + Tabelle.1195 + + + Tabelle.1196 + + + Tabelle.1197 + + + Tabelle.1198 + + + + + Sequenzfluss.1199 + Exact match + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Exactmatch + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.1200 + + Tabelle.1201 + + + + + + + + Tabelle.1202 + + + + Tabelle.1203 + + + + Tabelle.1204 + + + + Tabelle.1205 + + + Tabelle.1206 + + + Tabelle.1207 + + + Tabelle.1208 + + + Tabelle.1209 + + + Tabelle.1210 + + + Tabelle.1211 + + + Tabelle.1212 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.1213 + + Tabelle.1214 + + + + + + + + Tabelle.1215 + + + + Tabelle.1216 + + + + Tabelle.1217 + + + + Tabelle.1218 + + + Tabelle.1219 + + + Tabelle.1220 + + + Tabelle.1221 + + + Tabelle.1222 + + + Tabelle.1223 + + + Tabelle.1224 + + + Tabelle.1225 + + + + + Sequenzfluss.1226 + Deficit + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Deficit + + Sequenzfluss.1227 + Surplus + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surplus + + + + + + + + + + + + + + + + + + + + + + Gateway.1228 + + Tabelle.1229 + + + + Tabelle.1230 + + + + Tabelle.1231 + + Tabelle.1232 + + + Tabelle.1233 + + + + Tabelle.1234 + + + Tabelle.1235 + + + Tabelle.1236 + + + Tabelle.1237 + + Tabelle.1238 + + + + Tabelle.1239 + + + + Tabelle.1240 + + Tabelle.1241 + + + + Tabelle.1242 + + + + + Sequenzfluss.1243 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1244 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.1245 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.1246 + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_CoreProcess_SHORT.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_CoreProcess_SHORT.svg new file mode 100644 index 000000000..d701d2147 --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_CoreProcess_SHORT.svg @@ -0,0 +1,3673 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Prozess_SHORT + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CFF-Container + + Tabelle.2 + + + + + + + + + + Tabelle.3 + Titel + + + + + + + + + + + + + + + + + + + + + + + Verantwortlichkeitsbereichsliste + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CFF-Container.170 + + Tabelle.6 + + + + + + + + + + Tabelle.7 + Titel + + + + + + + + + + + + + + + + + + + + + + + Verantwortlichkeitsbereichsliste.173 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Pool/Verantwortlichkeitsbereich + + Tabelle.10 + + + + + + + + + + + Tabelle.11 + + + Tabelle.12 + Customer + + + + + + + + + + + + + + + + + + + Customer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Pool/Verantwortlichkeitsbereich.166 + + Tabelle.14 + + + + + + + + + + + Tabelle.15 + + + Tabelle.16 + Supplier + + + + + + + + + + + + + + + + + + + Supplier + + + Phasenliste + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Trennzeichen + + Tabelle.19 + + + + + + Tabelle.20 + Phase + + + + + + + + + + + + + + + + + + Phasenliste.174 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Trennzeichen.175 + + Tabelle.23 + + + + + + Tabelle.24 + Phase + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Startereignis + + Tabelle.26 + + + + + + + Tabelle.27 + + + + Tabelle.28 + + + + Tabelle.29 + + + + Tabelle.30 + + + Tabelle.31 + + + Tabelle.32 + + + Tabelle.33 + + + Tabelle.34 + + + Tabelle.35 + + + Tabelle.36 + + + Tabelle.37 + + + + + + + + + + + + + + + + + + + + + + + + + + + Startereignis.191 + + Tabelle.39 + + + + + + + Tabelle.40 + + + + Tabelle.41 + + + + Tabelle.42 + + + + Tabelle.43 + + + Tabelle.44 + + + Tabelle.45 + + + Tabelle.46 + + + Tabelle.47 + + + Tabelle.48 + + + Tabelle.49 + + + Tabelle.50 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.51 + Share Demands + + Tabelle.52 + + + + Tabelle.53 + + Tabelle.54 + + + + Tabelle.55 + + + + + Tabelle.56 + + + + + + + + + + + Tabelle.57 + + Tabelle.58 + + + + Tabelle.59 + + + + Tabelle.60 + + + + + + + Tabelle.61 + + + + + + + + + + + Tabelle.62 + + Tabelle.63 + + + + Tabelle.64 + + + Tabelle.65 + + + Tabelle.66 + + Tabelle.67 + + + + Tabelle.68 + + + + Tabelle.69 + + + Tabelle.70 + + + Tabelle.71 + + + Tabelle.72 + + + Tabelle.73 + + + + + + + + + Share Demands + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.227 + Share Capacities + + Tabelle.75 + + + + Tabelle.76 + + Tabelle.77 + + + + Tabelle.78 + + + + + Tabelle.79 + + + + + + + + + + + Tabelle.80 + + Tabelle.81 + + + + Tabelle.82 + + + + Tabelle.83 + + + + + + + Tabelle.84 + + + + + + + + + + + Tabelle.85 + + Tabelle.86 + + + + Tabelle.87 + + + Tabelle.88 + + + Tabelle.89 + + Tabelle.90 + + + + Tabelle.91 + + + + Tabelle.92 + + + Tabelle.93 + + + Tabelle.94 + + + Tabelle.95 + + + Tabelle.96 + + + + + + + + + Share Capacities + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.250 + Match & Compare + + Tabelle.98 + + + + Tabelle.99 + + Tabelle.100 + + + + Tabelle.101 + + + + + Tabelle.102 + + + + + + + + + + + Tabelle.103 + + Tabelle.104 + + + + Tabelle.105 + + + + Tabelle.106 + + + + + + + Tabelle.107 + + + + + + + + + + + Tabelle.108 + + Tabelle.109 + + + + Tabelle.110 + + + Tabelle.111 + + + Tabelle.112 + + Tabelle.113 + + + + Tabelle.114 + + + + Tabelle.115 + + + Tabelle.116 + + + Tabelle.117 + + + Tabelle.118 + + + Tabelle.119 + + + + + + + + + Match & Compare + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.273 + Match & Compare + + Tabelle.121 + + + + Tabelle.122 + + Tabelle.123 + + + + Tabelle.124 + + + + + Tabelle.125 + + + + + + + + + + + Tabelle.126 + + Tabelle.127 + + + + Tabelle.128 + + + + Tabelle.129 + + + + + + + Tabelle.130 + + + + + + + + + + + Tabelle.131 + + Tabelle.132 + + + + Tabelle.133 + + + Tabelle.134 + + + Tabelle.135 + + Tabelle.136 + + + + Tabelle.137 + + + + Tabelle.138 + + + Tabelle.139 + + + Tabelle.140 + + + Tabelle.141 + + + Tabelle.142 + + + + + + + + + Match & Compare + + + Sequenzfluss + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.144 + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.298 + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.299 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.300 + Review and Collaborate with Supply Chain Partner + + Tabelle.148 + + + + Tabelle.149 + + Tabelle.150 + + + + Tabelle.151 + + + + + Tabelle.152 + + + + + + + + + + + Tabelle.153 + + Tabelle.154 + + + + Tabelle.155 + + + + Tabelle.156 + + + + + + + Tabelle.157 + + + + + + + + + + + Tabelle.158 + + Tabelle.159 + + + + Tabelle.160 + + + Tabelle.161 + + + Tabelle.162 + + Tabelle.163 + + + + Tabelle.164 + + + + Tabelle.165 + + + Tabelle.166 + + + Tabelle.167 + + + Tabelle.168 + + + Tabelle.169 + + + + + + + + + Review and Collaborate with Supply Chain Partner + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.323 + Review and Collaborate with Supply Chain Partner + + Tabelle.171 + + + + Tabelle.172 + + Tabelle.173 + + + + Tabelle.174 + + + + + Tabelle.175 + + + + + + + + + + + Tabelle.176 + + Tabelle.177 + + + + Tabelle.178 + + + + Tabelle.179 + + + + + + + Tabelle.180 + + + + + + + + + + + Tabelle.181 + + Tabelle.182 + + + + Tabelle.183 + + + Tabelle.184 + + + Tabelle.185 + + Tabelle.186 + + + + Tabelle.187 + + + + Tabelle.188 + + + Tabelle.189 + + + Tabelle.190 + + + Tabelle.191 + + + Tabelle.192 + + + + + + + + + Review and Collaborate with Supply Chain Partner + + + Sequenzfluss.348 + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.349 + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.403 + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss.452 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss.455 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss.456 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss.457 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss.458 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.482 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe + Resolve Bottleneck & Surplus + + Tabelle.205 + + + + Tabelle.206 + + Tabelle.207 + + + + Tabelle.208 + + + + + Tabelle.209 + + + + + + + + + + + Tabelle.210 + + Tabelle.211 + + + + Tabelle.212 + + + + Tabelle.213 + + + + + + + Tabelle.214 + + + + + + + + + + + Tabelle.215 + + Tabelle.216 + + + + Tabelle.217 + + + Tabelle.218 + + + Tabelle.219 + + Tabelle.220 + + + + Tabelle.221 + + + + Tabelle.222 + + + Tabelle.223 + + + Tabelle.224 + + + Tabelle.225 + + + Tabelle.226 + + + + + + + + + Resolve Bottleneck & Surplus + + + Dynamischer Verbinder.498 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gateway + + Tabelle.229 + + + + Tabelle.230 + + + + Tabelle.231 + + Tabelle.232 + + + Tabelle.233 + + + + Tabelle.234 + + + Tabelle.235 + + + Tabelle.236 + + + Tabelle.237 + + Tabelle.238 + + + + Tabelle.239 + + + + Tabelle.240 + + Tabelle.241 + + + + Tabelle.242 + + + + + Dynamischer Verbinder.512 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Endereignis.15 + + Tabelle.245 + + + + + + + Tabelle.246 + + + + Tabelle.247 + + + + Tabelle.248 + + + + Tabelle.249 + + + Tabelle.250 + + + Tabelle.251 + + + Tabelle.252 + + + Tabelle.253 + + + Tabelle.254 + + + Tabelle.255 + + + Tabelle.256 + + + + + Dynamischer Verbinder.536 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.513 + Resolve Bottleneck & Surplus + + Tabelle.259 + + + + Tabelle.260 + + Tabelle.261 + + + + Tabelle.262 + + + + + Tabelle.263 + + + + + + + + + + + Tabelle.264 + + Tabelle.265 + + + + Tabelle.266 + + + + Tabelle.267 + + + + + + + Tabelle.268 + + + + + + + + + + + Tabelle.269 + + Tabelle.270 + + + + Tabelle.271 + + + Tabelle.272 + + + Tabelle.273 + + Tabelle.274 + + + + Tabelle.275 + + + + Tabelle.276 + + + Tabelle.277 + + + Tabelle.278 + + + Tabelle.279 + + + Tabelle.280 + + + + + + + + + Resolve Bottleneck & Surplus + + + Dynamischer Verbinder.552 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gateway.537 + + Tabelle.283 + + + + Tabelle.284 + + + + Tabelle.285 + + Tabelle.286 + + + Tabelle.287 + + + + Tabelle.288 + + + Tabelle.289 + + + Tabelle.290 + + + Tabelle.291 + + Tabelle.292 + + + + Tabelle.293 + + + + Tabelle.294 + + Tabelle.295 + + + + Tabelle.296 + + + + + Dynamischer Verbinder.566 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Endereignis.553 + + Tabelle.299 + + + + + + + Tabelle.300 + + + + Tabelle.301 + + + + Tabelle.302 + + + + Tabelle.303 + + + Tabelle.304 + + + Tabelle.305 + + + Tabelle.306 + + + Tabelle.307 + + + Tabelle.308 + + + Tabelle.309 + + + Tabelle.310 + + + + + Nachrichtenfluss.570 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss.571 + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_CoreProcess_with_Twins_BPMN.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_CoreProcess_with_Twins_BPMN.svg new file mode 100644 index 000000000..df94d0a87 --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_CoreProcess_with_Twins_BPMN.svg @@ -0,0 +1,6897 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zeichenblatt-1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CFF-Container.17 + + Tabelle.2 + + + + + + + + + + + + + Tabelle.3 + Titel + + + + + + + + + + + + + + + + + + + + + + + Verantwortlichkeitsbereichsliste.20 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CFF Container.102 + + Tabelle.6 + + + + + + + + + + + + + Tabelle.7 + Titel + + + + + + + + + + + + + + + + + + + + + + + Swimlane List.105 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Pool/Verantwortlichkeitsbereich.9 + + Tabelle.10 + + + + + + + + + + + + + + Tabelle.11 + + + + + + Tabelle.12 + Supplier + + + + + + + + + + + + + + + + + + + Supplier + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Pool / Lane.106 + + Tabelle.14 + + + + + + + + + + + + + + Tabelle.15 + + + + + + Tabelle.16 + Customer + + + + + + + + + + + + + + + + + + + Customer + + + Phasenliste.17 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Trennzeichen.18 + + Tabelle.19 + + + + + + + Tabelle.20 + Phase + + + + + + + + + + + + + + + + + + Phase List.110 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Separator.111 + + Tabelle.23 + + + + + + + Tabelle.24 + Phase + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Start Event + Start + + Tabelle.26 + + + + + + + Tabelle.27 + + + + Tabelle.28 + + + + Tabelle.29 + + + + Tabelle.30 + + + Tabelle.31 + + + Tabelle.32 + + + Tabelle.33 + + + Tabelle.34 + + + Tabelle.35 + + + Tabelle.36 + + + Tabelle.37 + + + + + Start + + + + + + + + + + + + + + + + + + + + + + + + + + + Start Event.114 + Start + + Tabelle.39 + + + + + + + Tabelle.40 + + + + Tabelle.41 + + + + Tabelle.42 + + + + Tabelle.43 + + + Tabelle.44 + + + Tabelle.45 + + + Tabelle.46 + + + Tabelle.47 + + + Tabelle.48 + + + Tabelle.49 + + + Tabelle.50 + + + + + Start + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis + Material Demand + + Tabelle.127 + + + + + + + Tabelle.128 + + + + Tabelle.129 + + + + Tabelle.130 + + + + Tabelle.131 + + + + + + + Tabelle.132 + + + Tabelle.133 + + + Tabelle.134 + + + Tabelle.135 + + + Tabelle.136 + + + Tabelle.137 + + + Tabelle.138 + + + + + Material Demand + + + Sequenzfluss.384 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.541 + Capacity Group + + Tabelle.246 + + + + + + + Tabelle.247 + + + + Tabelle.248 + + + + Tabelle.249 + + + + Tabelle.250 + + + + + + + Tabelle.251 + + + Tabelle.252 + + + Tabelle.253 + + + Tabelle.254 + + + Tabelle.255 + + + Tabelle.256 + + + Tabelle.257 + + + + + Capacity Group + + + Dynamischer Verbinder.739 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe + Manage Material Demand + + Tabelle.717 + + + + Tabelle.718 + + Tabelle.719 + + + + Tabelle.720 + + + + + Tabelle.721 + + + + + + + + + + + Tabelle.722 + + Tabelle.723 + + + + Tabelle.724 + + + + Tabelle.725 + + + + + + + Tabelle.726 + + + + + + + + + + + Tabelle.727 + + Tabelle.728 + + + + Tabelle.729 + + + Tabelle.730 + + + Tabelle.731 + + Tabelle.732 + + + + Tabelle.733 + + + + Tabelle.734 + + + Tabelle.735 + + + Tabelle.736 + + + Tabelle.737 + + + Tabelle.738 + + + + + + + + + Manage Material Demand + + + Dynamischer Verbinder.763 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.740 + Grant Supplier rights in Customer DTR + + Tabelle.741 + + + + Tabelle.742 + + Tabelle.743 + + + + Tabelle.744 + + + + + Tabelle.745 + + + + + + + + + + + Tabelle.746 + + Tabelle.747 + + + + Tabelle.748 + + + + Tabelle.749 + + + + + + + Tabelle.750 + + + + + + + + + + + Tabelle.751 + + Tabelle.752 + + + + Tabelle.753 + + + Tabelle.754 + + + Tabelle.755 + + Tabelle.756 + + + + Tabelle.757 + + + + Tabelle.758 + + + Tabelle.759 + + + Tabelle.760 + + + Tabelle.761 + + + Tabelle.762 + + + + + + + + + Grant Supplier rights in Customer DTR + + + Nachrichtenfluss.49 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.765 + Manage Capacity Group + + Tabelle.766 + + + + Tabelle.767 + + Tabelle.768 + + + + Tabelle.769 + + + + + Tabelle.770 + + + + + + + + + + + Tabelle.771 + + Tabelle.772 + + + + Tabelle.773 + + + + Tabelle.774 + + + + + + + Tabelle.775 + + + + + + + + + + + Tabelle.776 + + Tabelle.777 + + + + Tabelle.778 + + + Tabelle.779 + + + Tabelle.780 + + Tabelle.781 + + + + Tabelle.782 + + + + Tabelle.783 + + + Tabelle.784 + + + Tabelle.785 + + + Tabelle.786 + + + Tabelle.787 + + + + + + + + + Manage Capacity Group + + + Nachrichtenfluss.789 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.50 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.814 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.791 + Reference Capacity Group in Customer DTR + + Tabelle.792 + + + + Tabelle.793 + + Tabelle.794 + + + + Tabelle.795 + + + + + Tabelle.796 + + + + + + + + + + + Tabelle.797 + + Tabelle.798 + + + + Tabelle.799 + + + + Tabelle.800 + + + + + + + Tabelle.801 + + + + + + + + + + + Tabelle.802 + + Tabelle.803 + + + + Tabelle.804 + + + Tabelle.805 + + + Tabelle.806 + + Tabelle.807 + + + + Tabelle.808 + + + + Tabelle.809 + + + Tabelle.810 + + + Tabelle.811 + + + Tabelle.812 + + + Tabelle.813 + + + + + + + + + Reference Capacity Group in Customer DTR + + + Dynamischer Verbinder.838 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.815 + Grant Customer rights in Supplier DTR + + Tabelle.816 + + + + Tabelle.817 + + Tabelle.818 + + + + Tabelle.819 + + + + + Tabelle.820 + + + + + + + + + + + Tabelle.821 + + Tabelle.822 + + + + Tabelle.823 + + + + Tabelle.824 + + + + + + + Tabelle.825 + + + + + + + + + + + Tabelle.826 + + Tabelle.827 + + + + Tabelle.828 + + + Tabelle.829 + + + Tabelle.830 + + Tabelle.831 + + + + Tabelle.832 + + + + Tabelle.833 + + + Tabelle.834 + + + Tabelle.835 + + + Tabelle.836 + + + Tabelle.837 + + + + + + + + + Grant Customer rights in Supplier DTR + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.961 + DTR Link + + Tabelle.962 + + + + + + + Tabelle.963 + + + + Tabelle.964 + + + + Tabelle.965 + + + + Tabelle.966 + + + + + + + Tabelle.967 + + + Tabelle.968 + + + Tabelle.969 + + + Tabelle.970 + + + Tabelle.971 + + + Tabelle.972 + + + Tabelle.973 + + + + + DTR Link + + + Nachrichtenfluss.974 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.975 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.999 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.976 + Reference Material Demand in Supplier DTR + + Tabelle.977 + + + + Tabelle.978 + + Tabelle.979 + + + + Tabelle.980 + + + + + Tabelle.981 + + + + + + + + + + + Tabelle.982 + + Tabelle.983 + + + + Tabelle.984 + + + + Tabelle.985 + + + + + + + Tabelle.986 + + + + + + + + + + + Tabelle.987 + + Tabelle.988 + + + + Tabelle.989 + + + Tabelle.990 + + + Tabelle.991 + + Tabelle.992 + + + + Tabelle.993 + + + + Tabelle.994 + + + Tabelle.995 + + + Tabelle.996 + + + Tabelle.997 + + + Tabelle.998 + + + + + + + + + Reference Material Demand in Supplier DTR + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.1064 + DTR Link + + Tabelle.1065 + + + + + + + Tabelle.1066 + + + + Tabelle.1067 + + + + Tabelle.1068 + + + + Tabelle.1069 + + + + + + + Tabelle.1070 + + + Tabelle.1071 + + + Tabelle.1072 + + + Tabelle.1073 + + + Tabelle.1074 + + + Tabelle.1075 + + + Tabelle.1076 + + + + + DTR Link + + + Nachrichtenfluss.1077 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.557 + Analyze Capacity Group + + Tabelle.1079 + + + + Tabelle.1080 + + Tabelle.1081 + + + + Tabelle.1082 + + + + + Tabelle.1083 + + + + + + + + + + + Tabelle.1084 + + Tabelle.1085 + + + + Tabelle.1086 + + + + Tabelle.1087 + + + + + + + Tabelle.1088 + + + + + + + + + + + Tabelle.1089 + + Tabelle.1090 + + + + Tabelle.1091 + + + Tabelle.1092 + + + Tabelle.1093 + + Tabelle.1094 + + + + Tabelle.1095 + + + + Tabelle.1096 + + + Tabelle.1097 + + + Tabelle.1098 + + + Tabelle.1099 + + + Tabelle.1100 + + + + + + + + + Analyze Capacity Group + + + + + + + + + + + + + + + + + + + + + + + Gateway + + Tabelle.1102 + + + + Tabelle.1103 + + + + Tabelle.1104 + + Tabelle.1105 + + + Tabelle.1106 + + + + Tabelle.1107 + + + Tabelle.1108 + + + Tabelle.1109 + + + Tabelle.1110 + + Tabelle.1111 + + + + Tabelle.1112 + + + + Tabelle.1113 + + Tabelle.1114 + + + + Tabelle.1115 + + + + + Sequenzfluss.619 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Endereignis.15 + + Tabelle.1118 + + + + + + + Tabelle.1119 + + + + Tabelle.1120 + + + + Tabelle.1121 + + + + Tabelle.1122 + + + Tabelle.1123 + + + Tabelle.1124 + + + Tabelle.1125 + + + Tabelle.1126 + + + Tabelle.1127 + + + Tabelle.1128 + + + Tabelle.1129 + + + + + Sequenzfluss.692 + Exact match + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Exactmatch + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.693 + + Tabelle.1132 + + + + + + + + Tabelle.1133 + + + + Tabelle.1134 + + + + Tabelle.1135 + + + + Tabelle.1136 + + + Tabelle.1137 + + + Tabelle.1138 + + + Tabelle.1139 + + + Tabelle.1140 + + + Tabelle.1141 + + + Tabelle.1142 + + + Tabelle.1143 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.706 + + Tabelle.1145 + + + + + + + + Tabelle.1146 + + + + Tabelle.1147 + + + + Tabelle.1148 + + + + Tabelle.1149 + + + Tabelle.1150 + + + Tabelle.1151 + + + Tabelle.1152 + + + Tabelle.1153 + + + Tabelle.1154 + + + Tabelle.1155 + + + Tabelle.1156 + + + + + Sequenzfluss.719 + Deficit + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Deficit + + Sequenzfluss.720 + Surplus + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surplus + + + + + + + + + + + + + + + + + + + + + + Gateway.721 + + Tabelle.1160 + + + + Tabelle.1161 + + + + Tabelle.1162 + + Tabelle.1163 + + + Tabelle.1164 + + + + Tabelle.1165 + + + Tabelle.1166 + + + Tabelle.1167 + + + Tabelle.1168 + + Tabelle.1169 + + + + Tabelle.1170 + + + + Tabelle.1171 + + Tabelle.1172 + + + + Tabelle.1173 + + + + + Sequenzfluss.736 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.737 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.1200 + Analyze Capacity Group + + Tabelle.1201 + + + + Tabelle.1202 + + Tabelle.1203 + + + + Tabelle.1204 + + + + + Tabelle.1205 + + + + + + + + + + + Tabelle.1206 + + Tabelle.1207 + + + + Tabelle.1208 + + + + Tabelle.1209 + + + + + + + Tabelle.1210 + + + + + + + + + + + Tabelle.1211 + + Tabelle.1212 + + + + Tabelle.1213 + + + Tabelle.1214 + + + Tabelle.1215 + + Tabelle.1216 + + + + Tabelle.1217 + + + + Tabelle.1218 + + + Tabelle.1219 + + + Tabelle.1220 + + + Tabelle.1221 + + + Tabelle.1222 + + + + + + + + + Analyze Capacity Group + + + + + + + + + + + + + + + + + + + + + + + Gateway.1223 + + Tabelle.1224 + + + + Tabelle.1225 + + + + Tabelle.1226 + + Tabelle.1227 + + + Tabelle.1228 + + + + Tabelle.1229 + + + Tabelle.1230 + + + Tabelle.1231 + + + Tabelle.1232 + + Tabelle.1233 + + + + Tabelle.1234 + + + + Tabelle.1235 + + Tabelle.1236 + + + + Tabelle.1237 + + + + + Sequenzfluss.1238 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Endereignis.1239 + + Tabelle.1240 + + + + + + + Tabelle.1241 + + + + Tabelle.1242 + + + + Tabelle.1243 + + + + Tabelle.1244 + + + Tabelle.1245 + + + Tabelle.1246 + + + Tabelle.1247 + + + Tabelle.1248 + + + Tabelle.1249 + + + Tabelle.1250 + + + Tabelle.1251 + + + + + Sequenzfluss.1252 + Exact match + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Exactmatch + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.1253 + + Tabelle.1254 + + + + + + + + Tabelle.1255 + + + + Tabelle.1256 + + + + Tabelle.1257 + + + + Tabelle.1258 + + + Tabelle.1259 + + + Tabelle.1260 + + + Tabelle.1261 + + + Tabelle.1262 + + + Tabelle.1263 + + + Tabelle.1264 + + + Tabelle.1265 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.1266 + + Tabelle.1267 + + + + + + + + Tabelle.1268 + + + + Tabelle.1269 + + + + Tabelle.1270 + + + + Tabelle.1271 + + + Tabelle.1272 + + + Tabelle.1273 + + + Tabelle.1274 + + + Tabelle.1275 + + + Tabelle.1276 + + + Tabelle.1277 + + + Tabelle.1278 + + + + + Sequenzfluss.1279 + Deficit + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Deficit + + Sequenzfluss.1280 + Surplus + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surplus + + + + + + + + + + + + + + + + + + + + + + Gateway.1281 + + Tabelle.1282 + + + + Tabelle.1283 + + + + Tabelle.1284 + + Tabelle.1285 + + + Tabelle.1286 + + + + Tabelle.1287 + + + Tabelle.1288 + + + Tabelle.1289 + + + Tabelle.1290 + + Tabelle.1291 + + + + Tabelle.1292 + + + + Tabelle.1293 + + Tabelle.1294 + + + + Tabelle.1295 + + + + + Sequenzfluss.1296 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1297 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1298 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1299 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1300 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.1324 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.1301 + Align capacities and demands + + Tabelle.1302 + + + + Tabelle.1303 + + Tabelle.1304 + + + + Tabelle.1305 + + + + + Tabelle.1306 + + + + + + + + + + + Tabelle.1307 + + Tabelle.1308 + + + + Tabelle.1309 + + + + Tabelle.1310 + + + + + + + Tabelle.1311 + + + + + + + + + + + Tabelle.1312 + + Tabelle.1313 + + + + Tabelle.1314 + + + Tabelle.1315 + + + Tabelle.1316 + + Tabelle.1317 + + + + Tabelle.1318 + + + + Tabelle.1319 + + + Tabelle.1320 + + + Tabelle.1321 + + + Tabelle.1322 + + + Tabelle.1323 + + + + + + + + + Align capacities and demands + + + Dynamischer Verbinder.1348 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.1325 + Align capacities and demands + + Tabelle.1326 + + + + Tabelle.1327 + + Tabelle.1328 + + + + Tabelle.1329 + + + + + Tabelle.1330 + + + + + + + + + + + Tabelle.1331 + + Tabelle.1332 + + + + Tabelle.1333 + + + + Tabelle.1334 + + + + + + + Tabelle.1335 + + + + + + + + + + + Tabelle.1336 + + Tabelle.1337 + + + + Tabelle.1338 + + + Tabelle.1339 + + + Tabelle.1340 + + Tabelle.1341 + + + + Tabelle.1342 + + + + Tabelle.1343 + + + Tabelle.1344 + + + Tabelle.1345 + + + Tabelle.1346 + + + Tabelle.1347 + + + + + + + + + Align capacities and demands + + + Dynamischer Verbinder.1365 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gateway.1350 + + Tabelle.1351 + + + + Tabelle.1352 + + + Tabelle.1353 + + Tabelle.1354 + + + Tabelle.1355 + + + + Tabelle.1356 + + + + Tabelle.1357 + + + Tabelle.1358 + + + Tabelle.1359 + + Tabelle.1360 + + + + Tabelle.1361 + + + + Tabelle.1362 + + Tabelle.1363 + + + + Tabelle.1364 + + + + + Dynamischer Verbinder.1389 + Align by capacity adjustment + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Align by capacity adjustment + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.1366 + Update Capacity Group via PatchSubModel + + Tabelle.1367 + + + + Tabelle.1368 + + Tabelle.1369 + + + + Tabelle.1370 + + + + + Tabelle.1371 + + + + + + + + + + + Tabelle.1372 + + Tabelle.1373 + + + + Tabelle.1374 + + + + Tabelle.1375 + + + + + + + Tabelle.1376 + + + + + + + + + + + Tabelle.1377 + + Tabelle.1378 + + + + Tabelle.1379 + + + Tabelle.1380 + + + Tabelle.1381 + + Tabelle.1382 + + + + Tabelle.1383 + + + + Tabelle.1384 + + + Tabelle.1385 + + + Tabelle.1386 + + + Tabelle.1387 + + + Tabelle.1388 + + + + + + + + + Update Capacity Group via PatchSubModel + + + Dynamischer Verbinder.1482 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gateway.1467 + + Tabelle.1468 + + + + Tabelle.1469 + + + Tabelle.1470 + + Tabelle.1471 + + + Tabelle.1472 + + + + Tabelle.1473 + + + + Tabelle.1474 + + + Tabelle.1475 + + + Tabelle.1476 + + Tabelle.1477 + + + + Tabelle.1478 + + + + Tabelle.1479 + + Tabelle.1480 + + + + Tabelle.1481 + + + + + Dynamischer Verbinder.1506 + Align by demand adjustment + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Align by demand adjustment + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Aufgabe.1483 + Update Material Demand via PatchSubModel + + Tabelle.1484 + + + + Tabelle.1485 + + Tabelle.1486 + + + + Tabelle.1487 + + + + + Tabelle.1488 + + + + + + + + + + + Tabelle.1489 + + Tabelle.1490 + + + + Tabelle.1491 + + + + Tabelle.1492 + + + + + + + Tabelle.1493 + + + + + + + + + + + Tabelle.1494 + + Tabelle.1495 + + + + Tabelle.1496 + + + Tabelle.1497 + + + Tabelle.1498 + + Tabelle.1499 + + + + Tabelle.1500 + + + + Tabelle.1501 + + + Tabelle.1502 + + + Tabelle.1503 + + + Tabelle.1504 + + + Tabelle.1505 + + + + + + + + + Update Material Demand via PatchSubModel + + + Nachrichtenfluss.1510 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss.1511 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.1516 + Material Demand + + Tabelle.1517 + + + + + + + Tabelle.1518 + + + + Tabelle.1519 + + + + Tabelle.1520 + + + + Tabelle.1521 + + + + + + + Tabelle.1522 + + + Tabelle.1523 + + + Tabelle.1524 + + + Tabelle.1525 + + + Tabelle.1526 + + + Tabelle.1527 + + + Tabelle.1528 + + + + + Material Demand + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zwischenereignis.1529 + Capacity Group + + Tabelle.1530 + + + + + + + Tabelle.1531 + + + + Tabelle.1532 + + + + Tabelle.1533 + + + + Tabelle.1534 + + + + + + + Tabelle.1535 + + + Tabelle.1536 + + + Tabelle.1537 + + + Tabelle.1538 + + + Tabelle.1539 + + + Tabelle.1540 + + + Tabelle.1541 + + + + + Capacity Group + + + Nachrichtenfluss.1542 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nachrichtenfluss.1543 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1544 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1545 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.1975 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dynamischer Verbinder.1976 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1981 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1982 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1983 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sequenzfluss.1984 + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_CG_Structure.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_CG_Structure.svg new file mode 100644 index 000000000..14d617956 --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_CG_Structure.svg @@ -0,0 +1 @@ +CapacityGroup 1W22/22W21/22W20/22W19/22W18/22W17/22W16/22W15/22W14/22W13/22W12/22W11/22W10/22DemandCategoryDemandLocation190175300410280100340207205175180210180SeriesMadrid……Demand Time Series 1210230190200190190275250420390400300100AfterSalesBerlin………Demand Time Series 2…Material Demand HeaderJologaSupplier:500009086MaterialNumber:HelsinkiExpectedSupplierLocation:Jun, 15 2021Lastupdated:PCUnitofMeasure:CapacityGroup 2 \ No newline at end of file diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_CapacityData.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_CapacityData.svg new file mode 100644 index 000000000..0b060d180 --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_CapacityData.svg @@ -0,0 +1 @@ +0100020003000400050006000Week 1Week 2Week 3Week 4Week 5Week 6Week 7Week 8Example:CapacityDataActual CapacityMaximum CapacityAgreed Capacity \ No newline at end of file diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandData.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandData.svg new file mode 100644 index 000000000..249359fe7 --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandData.svg @@ -0,0 +1 @@ +0100020003000400050006000Week 1Week 2Week 3Week 4Week 5Week 6Week 7Week 8Example: Demand DataDemand \ No newline at end of file diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandDeviationAndAlertThreshold.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandDeviationAndAlertThreshold.svg new file mode 100644 index 000000000..514eff331 --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandDeviationAndAlertThreshold.svg @@ -0,0 +1 @@ +CW25CW24CW23CW22CW21KeyfiguresDemandvolatilityatcapacitygrouplevel520515386411458Previousdemand: CW8Capacitygroup:550495393392444Latestdemand: CW9CG14.5%Max. rel. pos.deviation-4.5%Max. rel. neg.deviation30-207-19-14∆abs=Underlyingdemandseries:5.45%-4.04%1.78%-4.85%3.15%∆rel=DS1 & DS2 & DS3 \ No newline at end of file diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandDeviationCalculation.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandDeviationCalculation.svg new file mode 100644 index 000000000..b6987a11a --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandDeviationCalculation.svg @@ -0,0 +1 @@ +CW25CW24CW23CW22CW21DatetimeKey FigureCapacityGroupAssign.DemandCategoryCustomer LocationCustomer MaterialDemand Series1301459311012402.02.2024–8pmCETCW8previousdemandCG1SeriesBerlinADS11601251009111009.02.2024–8pmCETCW9latestdemand23%-14%8%-17%-11%deviation1601251009111002.02.2024–8pmCETCW8previousforecastCG1After-SalesStuttgartADS21301459311012409.02.2024–8pmCETCW9latestdemand-19%16%-7%21%13%deviation23024519321022402.02.2024–8pmCETCW8previousforecastCG1SeriesBerlinBDS326022520019121009.02.2024–8pmCETCW9latestdemand13%-8%4%-9%-6%deviation52051538641145819.02.2024–8pmCETCW8previousforecastDemand volatility at Capacity Group level55049539339244426.02.2024–8pmCETCW9latestdemandCapacityGroup: CG130-207-19-14∆abs=Underlying Demand Series: DS1 & DS2 & DS35.45%-4.04%1.78%-4.85%-3.15%∆rel= \ No newline at end of file diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandDeviationSubHorizons.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandDeviationSubHorizons.svg new file mode 100644 index 000000000..bf225001a --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_DemandDeviationSubHorizons.svg @@ -0,0 +1 @@ +Rolling HorizonLongtermHorizonDCM Volatility FocusHorizonOperational HorizonFrozenHorizon20252024CW10CW9CW8CW7…CW23CW22CW21CW20CW19CW18CW17CW16CW15CW14CW13CW12CW11CW10CW9CW8Week 104…Week 53Week 52...Week 15Week 14Week 13Week 12Week 11Week 10Week 9Week 8Week 7Week 6Week 5Week 4Week 3Week 2Week 1Week 0nothreshold35%35%35%20%20%20%10%10%10%10%10%10%5%5%5%5%0%Threshold∆rel, pos.nothresholdnothreshold-40%-40%-40%-20%-20%-20%-20%-20%-20%-10%-10%-10%-10%0%Threshold∆rel, neg.nothresholdnothresholdnothresholdnothresholdnothresholdnothresholdThreshold∆abs, pos.nothresholdnothresholdnothresholdnothresholdnothresholdnothresholdThreshold∆abs, neg.NosubhorizonSubhorizon5(l=37)Subhorizon4(l=3)Subhorizon3(l=6)Subhorizon2(l=4)Subhorizon1(l=2) \ No newline at end of file diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_MD_Structure.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_MD_Structure.svg new file mode 100644 index 000000000..30119d63b --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_MD_Structure.svg @@ -0,0 +1 @@ +W22/22W21/22W20/22W19/22W18/22W17/22W16/22W15/22W14/22W13/22W12/22W11/22W10/22DemandCategoryDemandLocation190175300410280100340207205175180210180SeriesMadrid……Demand Time Series 1210230190200190190275250420390400300100AfterSalesBerlin………Demand Time Series 2…Material Demand HeaderJologaSupplier:500009086MaterialNumber:HelsinkiExpectedSupplierLocation:Jun, 15 2021Lastupdated:PCUnitofMeasure: \ No newline at end of file diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_MatchAndCompare.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_MatchAndCompare.svg new file mode 100644 index 000000000..07fda04a7 --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_MatchAndCompare.svg @@ -0,0 +1 @@ +0100020003000400050006000Week 1Week 2Week 3Week 4Week 5Week 6Week 7Week 8Example: Demand andCapacityDataMatchingandComparisonwithinCapacityGroupDemand over actual capacityDemand within actual capacityDemand over actual but within maximum capacityActual capacityMaximum capacityAgreed capacity \ No newline at end of file diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_PostProduction.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_PostProduction.svg new file mode 100644 index 000000000..fa1b3148a --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_PostProduction.svg @@ -0,0 +1 @@ +0100020003000400050006000Week 1Week 2Week 3Week 4Week 5Week 6Week 7Week 8Example: Post-ProductionwithinaCapacityGroupDemand over actual capacityDemand within actual capacityDemand over actual but within maximum capacityActual capacityMaximum capacityDelta-productionAgreed capacity-D+D \ No newline at end of file diff --git a/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_PreProduction.svg b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_PreProduction.svg new file mode 100644 index 000000000..7a319e124 --- /dev/null +++ b/docs/standards/CX-0128-DemandandCapacityManagementDataExchange/assets/DCM_Example_PreProduction.svg @@ -0,0 +1 @@ +0100020003000400050006000Week 1Week 2Week 3Week 4Week 5Week 6Week 7Week 8Example:Pre-ProductionwithinaCapacityGroupDemand over actual capacityDemand within actual capacityDemand over actual but within maximum capacityActual capacityMaximum capacityDelta-productionAgreed capacity+D-D+D \ No newline at end of file diff --git a/docs/standards/CX-0129-RequestforQuotationExchange/CX-0129-RequestforQuotationExchange.md b/docs/standards/CX-0129-RequestforQuotationExchange/CX-0129-RequestforQuotationExchange.md new file mode 100644 index 000000000..4cfdd5a3f --- /dev/null +++ b/docs/standards/CX-0129-RequestforQuotationExchange/CX-0129-RequestforQuotationExchange.md @@ -0,0 +1,718 @@ +# CX-0129 Request for Quotation Exchange v2.0.0 + +## ABSTRACT + +Manufacturing-as-a-Service (MaaS) scenarios focus on connecting buyers having a request for specific +manufacturing process steps or products to be manufactured with the appropriate manufacturing +supplier, who has the corresponding capabilities and resources. + +A Request for Quotation defines detailed requirements, deadlines and evaluation criteria for +obtaining quotations from potential manufacturers for specific products or services. + +Sharing information about the demand with all required configuration and contact data is necessary +for potential suppliers to evaluate the request and formulate an offer. + +A common description of the request for quotation based on a standardized semantic definition is +therefore key for facilitating such an information exchange between Catena-X participants. This +ensures an open network for every Catena-X member to join and enables interoperability between the +partners. + +This document describes and standardizes the semantic model of Request for Quotation used in +Catena-X and the associated API. + +## FOR WHOM IS THE STANDARD DESIGNED + +The Request for Quotation standard is designed to benefit both manufacturing buyers and suppliers. +For buyers, it ensures that their request configuration is accurate and contains all necessary +product manufacturing information. Analogously, manufacturing suppliers benefit from this standard +through precise and unambiguous requirements and specifications and can therefore use the +formalization to make better decisions regarding cost, delivery date, and feasibility in a more +automated manner. + +With this standard the buyer user can configure its request once and spread it within the Catena-X +network where every interested supplier is able to implement this standard and receive the request +in a Catena-X standardized format. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +In this version of the standard, the processes entity of the RequestForQuotation semantic model has +been replaced by the "Bill of Process" data model (cf. [Chapter 3.2](#32-aspect-model-bill-of-process)). + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for suppliers to be able to receive and assess in an automated manner a +manufacturing request coming from digital market-ecosystems. Buyers can use this standard to request +a manufacturing process and reach as many suppliers as possible over digital market-ecosystems. +Defining this standard should help integrate new interested parties on every level e.g. new buyer +applications, configuring a manufacturing request or new suppliers processing manufacturing +requests, represented as ODM platforms, supplier networks or single suppliers applications. + +This standard is therefore relevant for the following roles : + +- **Data Providers** willing to provide the necessary information about their manufacturing request +- **Data Consumers** interested in receiving and processing requests for products or components +- **Business Application Providers** interested in providing solutions implementing this standard + +The scope of this standard is only the *Request-for-Quotation* aspect model and an API defining the +exchange of *Request-for-Quotation* data through a connector conformant to [[CX-0018]](#61-normative-references) (e.g. Tractus-X EDC). + +Only the initial exchange of the Request-for-Quotation from the buyer to the supplier is defined by +this standard. The subsequent steps of the bidding process happening in the later stages of the RFQ +communication (e.g. a response with an offer) are not in the scope of the standard. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +In the context of MaaS, the buyer uses an application (e.g. MaaS Portal) to formalize his request. +To generate a new request, the buyer follows a defined workflow with uploading the required part +geometry via CAD file, defining material and selecting required manufacturing methods, including +additional post processes and quality definitions. Additional services for automated generation of a +Bill of Process (e.g. Process Derivation Service) may also be available. When processed, this +information is used for capability matchmaking (e.g. by a Manufacturing Network Registry) and +listing potential manufacturers, which are able to manufacture the part requested by the buyer. To +get in contact with a certain manufacturer, the required request information is formalized with the +standardized RFQ aspect model and sent to the respective supplier application via the standardized +RFQ API. The supplier application might be an ODM platform, a manufacturer network application, or a +single manufacturer application (e.g. ERP). + +This necessary information, which is provided by the buyer to the supplier, is referred to as RFQ. +(Request for Quotation). This is the common usage of the RFQ in the context of MaaS. The contents of +the RFQ provides a detailed information about the requirements from the buyer side with respect to +the component that is needed. Upon receiving the buyer's RFQ, the manufacturer is able to analyze +the information provided in the standardized format and proceed to the bidding process. + +*Figure 1* shows the high-level architecture of the *Request-for-Quotation*exchange in the Catena-X +dataspace and the central services that are involved. Both the data provider and the data consumer +must be members of the Catena X network in order to communicate with each other. With the help of +centrally managed Identity Access Management (IAM) each participant can authenticate itself, verify +the identity of the requesting party and decide whether to authorize the request. + +![Figure 1: High-level architecture of the Request-for-Quotation exchange in the Catena-X network_](./assets/Figure_1.svg) +*Figure 1: High-level architecture of the Request-for-Quotation exchange in the Catena-X network* + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, +**SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in [BCP 14] +[[RFC2119]](#62-non-normative-references) [[RFC8174]](#62-non-normative-references) when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X +standards. To validate that the standards are applied correctly, Catena-X employs Conformity +Assessment Bodies (CABs). The proof of conformity for a single semantic model is done according to +the general rules for proving the conformity of data provided to a semantic model or the ability to +consume the corresponding data. + +### 1.4 EXAMPLES + +The following example shows a value-only JSON serialization of the Request-for-Quotation aspect model: + +```json +{ + "rfqConfiguration": { + "firstDeliveryDate": "2023-10-24", + "additionalFiles": { + "fileName": "Drehteil_technical", + "fileObject": {}, + "fileType": "pdf", + "filePath": "{{PATH_TO_ADDITIONAL_FILE}}" + }, + "cadFile": { + "fileName": "Drehteil", + "fileObject": {}, + "fileType": "STEP", + "filePath": "{{PATH_TO_CAD_FILE}}" + }, + "additionalComments": "this is a prototype, recommendations towards design for manufacturing are highly welcome", + "parts": { + "generalTolerance": "ISO 2768-1 (m)", + "processes": { + "processStepIdentifier": "surfacefinishing_color", + "subProcessSteps": {}, + "processProperties": { + "value": "black", + "propertyName": "color", + "valueType": "string" + } + }, + "manufacturingDomain": "additive manufacturing", + "material": { + "materialFamily": "aluminum", + "materialProperties": { + "value": "2.7", + "propertyName": "density", + "valueType": "g/cm3" + } + }, + "partId": "Drehteil", + "additionalRequirements": "premium quality check", + "partQuantity": { + "quantityNumber": 1, + "measurementUnit": "unit:piece" + }, + "partName": "Drehteil" + }, + "orderQuantity": { + "quantityNumber": 100, + "measurementUnit": "unit:piece" + }, + "lastDeliveryDate": "2023-12-24" + }, + "rfqIdentification": { + "rfqVersion": "1.0.0", + "rfqName": "Drehteil", + "rfqDateTime": "2023-10-24T14:48:54.709Z", + "rfqSource": "https://maasportal.mendixcloud.com/", + "rfqId": "Drehteil_02_0815" + }, + "cxHeader": { + "senderBpn": "BPNL7588787849VQ", + "relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy": "2023-06-19T21:24:00+07:00", + "context": "urn:samm:io.catenax.request_for_quotation:3.0.0", + "messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn": "BPNL6666787765VQ", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "urn:samm:io.catenax.shared.message_header:3.0.0" + }, + "rfqSender": { + "deliveryRequirements": "no plastic for packaging", + "senderName": "John Doe", + "senderAddress": "Sunstreet 1, 5555 Sunstate", + "senderPhoneNumber": "555 123456", + "senderEMail": "johndoe@sunny.com", + "senderDeliveryAddress": "Mystreet 1, 1234 Mystate", + "senderAccountAddress": "Accountstreet 1, 1234 Accountstate", + "senderCompanyName": "ManufactureEnterprise" + } +} +``` + +The following example shows a value-only JSON serialization of the Bill of Process aspect model: + +```json +{ + "billOfProcessModel" : { + "billOfProcessIdentification" : "box-with-lid-12345678-bill-of-process", + "version" : "1.0.0", + "productName" : "3D printed box with Lid", + "productVersion" : "box-with-lid-1.0.0", + "process" : [ { + "processStepIdentifier" : [ "001_3D-print-parts" ], + "processStepType" : "IsFirstElement", + "capabilityId" : "urn:manufacturing-capability:capability:3d-printing", + "precedenceRelation" : [ { + "precedenceElements" : [ { + "successor" : [ "002_screw_bolt_01", "003_screw_bolt_02" ] + } ] + } ] + }, + { + "processStepIdentifier" : [ "002_screw_bolt_01" ], + "processStepType" : "IsLastElement", + "capabilityId" : "urn:manufacturing-capability:capability:screwing", + "inputParameters" : [ { + "name" : "max_torque", + "parameterKey" : "HasValue", + "semanticReference" : [ "0173-1#02-ABK233#001" ], + "value" : "10" + } ], + "outputParameters" : [ { + "name": "max_torque", + "parameterKey": "HasNoValue", + "semanticReference": [ "0173-1#02-ABK233#001" ] + } ] + }, + { + "processStepIdentifier" : [ "002_screw_bolt_02" ], + "processStepType" : "IsLastElement", + "capabilityId" : "urn:manufacturing-capability:capability:screwing", + "inputParameters" : [ { + "name" : "max_torque", + "parameterKey" : "HasValue", + "semanticReference" : [ "0173-1#02-ABK233#001" ], + "value" : "10" + } ], + "outputParameters" : [ { + "name": "max_torque", + "parameterKey": "HasNoValue", + "semanticReference": [ "0173-1#02-ABK233#001" ] + } ] + }] + } +} +``` + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +| Term | Description +| --- | --- +| Manufacturer | Organization providing a manufacturing service to others, such as milling or drilling. +| RFQ | Request for Quotation +| ODM | On demand manufacturing platform +| Product | A Product is a material good or an (immaterial) service offering which is an outcome (output product) or an input (input product) of a Process. Inherits relations from Entity and Asset. + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 Request for Quotation + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +The following Catena-X standards are prerequisite for the implementation of this standard and therefore +**MUST** be considered / implemented by the relevant parties specified in each of them. + +| **Number** | **Standard** | **Version** +| --- | --- | --- +| [[CX-0001]](#61-normative-references) | EDC Discovery API | 1.0.2 +| [[CX-0003]](#61-normative-references) | SAMM Aspect Meta Model | 1.1.0 +| [[CX-0006]](#61-normative-references) | Registration and initial onboarding | 2.0.0 +| [[CX-0010]](#61-normative-references) | Business Partner Number (BPN) | 2.0.0 +| [[CX-0018]](#61-normative-references) | Dataspace Connectivity | 3.0.0 + +#### 2.1.2 DATA REQUIRED + +No additional data requirements. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### CONVENTIONS FOR USE CASE POLICY IN CONTEXT DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization +of data within the Catena-X use cases has been outlined. A set of specific policies on data offering +and data usage level detail the conditions under which data may be accessed, shared, and used, +ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data +usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository [[CX-ODRL]](#62-non-normative-references). This document provides in-depth explanations of the + terms and conditions applied to data access and utilization, ensuring that all engagement with our data + is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. + Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +###### ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for +members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, +Data Provider maintains control over its anti-trust obligations when sharing certain data. In +particular, Data Provider may apply Access Policies to restrict access to a particular data offer +for only one Participant identified by a specific business partner number. + +- Membership +- BPNL + +###### ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use +the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are +provided via the ODRL policy repository [[CX-ODRL]](#62-non-normative-references). + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +This version of the document does not define any requirements for standardized integration and +governance of digital twins. + +## 3 ASPECT MODELS + +> *This section is* *normative* + +### 3.1 ASPECT MODEL "Request for Quotation" + +This section describes the "Request for Quotation" semantic model used in the Catena-X network. + +#### 3.1.1 INTRODUCTION + +A Request for Quotation defines detailed requirements, deadlines and evaluation criteria for +obtaining quotations from potential manufacturers for specific products or services. The provided +aspect model is automotive-agonistic, thus allowing for future integration and exchange with +non-automotive dataspaces. For the complete semantics and detailed description of its properties +refer to the SAMM model in [Chapter 3.1.5.1](#3151-rdf-turtle). + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the +"semantic driven workflow" to create a submodel template specification [[SMT]](#62-non-normative-references). + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [[CX-0003]](#61-normative-references) as +input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to [[CX-0003]](#61-normative-references). + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + urn:samm:io.catenax.request_for_quotation:3.0.0 +``` + +This identifier **MUST** be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating +additional file formats and serializations. + +> [https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.request_for_quotation/3.0.0/RequestForQuotation.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.request_for_quotation/3.0.0/RequestForQuotation.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +Figure 2 shows all properties of the aspect model: +![Figure 2: Properties defined in the Request for Quotation aspect model](./assets/Figure_2.svg) +*Figure 2: Properties defined in the Request for Quotation aspect model* + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema **MUST** be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation *"GetSubmodel"*. + +##### 3.1.5.3 AASX + +An AASX file **MUST** be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to [[SMT]](#62-non-normative-references). + +### 3.2 ASPECT MODEL "Bill of Process" + +This section describes the "Bill of Process" semantic model used in the Catena-X network. + +#### 3.2.1 INTRODUCTION + +The bill of process aspect model is a data model that can be utilised to describe and exchange +information about the manufacturing process of a product between partners. The aspect model can be +used to represent a wide variety of (industrial) processes from different sectors and isn't limited +to the automotive industry. The purpose of this model is to specify an extended precedence graph +that features the parameter flow between individual process steps. The model is a shared aspect to +be included in other aspect models and is referenced within the RFQ data model described above, the +Shop Floor Information Service Production Tracking data model defined in [[CX-0142]](#61-normative-references) and the +Manufacturing Capability data model defined in [[CX-0115]](#61-normative-references). For the complete semantics and detailed +description of its properties refer to the SAMM modelin [Chapter 3.2.5.1](#3251-rdf-turtle). + +#### 3.2.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the +"semantic driven workflow" to create a submodel template specification [[SMT]](#62-non-normative-references). + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [[CX-0003]](#61-normative-references) as +input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to [[CX-0003]](#61-normative-references). + +#### 3.2.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.2.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + urn:samm:io.catenax.shared.bill_of_process:1.1.0 +``` + +This identifier **MUST** be used by the data provider to define the semantics of the data being transferred. + +#### 3.2.5 FORMATS OF SEMANTIC MODEL + +##### 3.2.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating +additional file formats and serializations. + +> [https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shared.bill_of_process/1.1.0/BillOfProcessSharedAspect.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shared.bill_of_process/1.1.0/BillOfProcessSharedAspect.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +Figure 3 shows all properties of the aspect model: +![Figure 3: Properties defined in the Bill of Process aspect model](./assets/Figure_3.svg) +*Figure 3: Properties defined in the Bill of Process aspect model* + +For more detailed information, including specific JSON examples for different cases and additional graphics to further aid in understanding and utilizing the data model, please refer to the README that accompanies the data model: [https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shared.bill_of_process/1.0.0/README.md](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shared.bill_of_process/1.0.0/README.md) + +The following table provides an overview of all fields, their properties and example values: + +|Field|Level|REQUIRED|Purpose|Data Type|Example Value (JSON) +|--- |--- |--- |--- |--- |--- +|version|BillOfProcess|mandatory|version of the bill of process model used for compatibility checks|VersionCharacteristic|`"version": "1.0.0"` +|billOfProcessIdentifier|BillOfProcess|mandatory|unique identifier for a bill of process that can be used to reference instances|String|`"billOfProcessIdentifier": "www.1234-bar-chair-billOfProcess.de"` +|productName|BillOfProcess|mandatory|name of the product whose production steps are specified within the bill of process|String|`"productName": "Bar Chair"` +|productVersion|BillOfProcess|mandatory|version of the product whose manufacturing steps are specified with the bill of process|String|`"productVerseion": "bar_chair_1.0.0"` +|process|BillOfProcess|mandatory|list that contains all manufacturing steps of a product, where each manufacturing step refers to exactly one capability. This list contains all process steps that are required to manufacture the product|ProcessStep|Due to limited space refer to [Chapter 1.4](#14-examples) +|processStepIdentifier|ProcessStep|mandatory|unique identifier for a specific process step|String|`"processStepIdentifier": "1234-transport"` +|capabilityReference|ProcessStep|mandatory|reference that points to a manufacturing capability that must be performed on a product to accomplish the corresponding process step|String|`"capabilityReference": "urn:manufacturing-capability:capability:42"` +|inputParameters|ProcessStep|optional|list of parameters that are required to execute the corresponding process step|Parameter|Due to limited space refer to [Chapter 1.4](#14-examples) +|outputParameters|ProcessStep|optional|list of parameters that are returned from the process step and can be used as inputParameters for subsequent steps|Parameter|Due to limited space refer to [Chapter 1.4](#14-examples) +|processStepType|ProcessStep|mandatory|distinguishes process steps based on whether there are the first or last process step to be executed, a regular process step or if they are a subprocess step, which subdivides a higher-level process step into smaller process steps. Possibile values: IsFirstElement, IsLastElement, IsProcessElement, IsSubProcessElement.|Enum|`"processStepType": "IsFirstElement"` +|precedenceRelation|ProcessStep|optional|list of alternative process steps from which the manufacturer has to select exactly one step to be executed. In case there are no alternative process steps, the list features only one element. In case of the last element, the property is not used, since the process step has no successor.|PrecedenceElements|JSON-Examples for Precedence Relations +|childProcessStep|ProcessStep|optional|list of child processes that need to be executed to complete the parent process step. It enables the expression of hierarchies between capabilities, e.g. a transport capability needs to execute at least a pick, a move and a place capability.|processStepIdentifier|`"childProcessSteps": [ "pick", "move", "place" ]` +|precedenceElements|PrecedenceElements|mandatory|list of process steps that must be executed in parallel|PrecedenceElement|JSON-Examples for Precedence Relations +|successor|PrecedenceElement|mandatory|list of subsequent process step which can be executed in any order|processStepIdentifier|`"successor" : [ "5678-milling" ]` +|name|Parameter|mandatory|name of the parameter|String|`"name": "volume"` +|value|Parameter|optional|value of the parameter|String|`"value": "{\"height\" : \"5\", \"length\" : \"3\", \"width\" : \"7\"}"` +|semanticReference|Parameter|mandatory|reference to a semantic namespace in which the type of the parameter is defined|String|`"semanticReference": [ "0173-1#02-AAZ883#001" ]` +|valueRangeList|Parameter|optional|list with value ranges for a parameter|ValueRange|Due to limited space refer to [Chapter 1.4](#14-examples) +|tolerances|Parameter|optional|list with tolerances for a parameter|TolerancesEntity|Due to limited space refer to [Chapter 1.4](#14-examples) +|parameterKey|Parameter|mandatory|enumeration that is used to distinguish whether the parameter has no value, has a value, has a value range or has a value with tolerances. Possible values: HasValue, HasNoValue, HasValueRange, HasTolerances.|Enum|`"parameterKey": "HasNoValue"` +|name|ValueRange|optional|name of the (sub-)parameter to which the value range applies|String|`"name": "height"` +|lowerValue|ValueRange|mandatory|lower boundary of a value range item|String|`"lowerValue": "12"` +|upperValue|ValueRange|mandatory|upper boundary for a value range item|String|`"upperValue": "36"` +|name|TolerancesEntity|optional|name of the (sub-)parameter to which the tolerances apply|String|`"name": "height"` +|lowerLimit|TolerancesEntity|mandatory|lower direct limit of the tolerance|String|`"lowerLimit": "4.9"` +|upperLimit|TolerancesEntity|mandatory|upper direct limit of the tolerance|String|`"upperLimit": "5.1"` + +##### 3.2.5.2 JSON SCHEMA + +A JSON Schema **MUST** be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation *"GetSubmodel"*. + +##### 3.2.5.3 AASX + +An AASX file **MUST** be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to [[SMT]](#62-non-normative-references). + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +### 4.1 "Request for Quotation" API + +The Request for Quotation API defined in this section enables the exchange of the *Request for +Quotation* data between Catena-X participants in an interoperable manner. *Figure 4* shows a high +level overview of the intended data exchange flow. + +![Figure 4: Request for Quotation data exchange overview](./assets/Figure_4.svg) +*Figure 4: Request for Quotation data exchange overview* + +The API relies on synchronous communication between the involved parties. + +1. A data exchange is initiated by the data provider (buyer) sending a POST request to the data + consumer (supplier) to create a Request For Quotation. +2. Upon receiving a valid request, the consumer (supllier) sends back a `201 Created` response to + indicate that the Request For Quotation has been successfully created. + +#### 4.1.1 PRECONDITIONS AND DEPENDENCIES + +To participate in the Catena-X dataspace, both the data consumer and the data provider **MUST** be +registered and onboarded as defined in [[CX-006]](#61-normative-references). + +A dataspace connector conformant to [[CX-0018]](#61-normative-references) **MUST** be used +to make the Request for Quotation API available to network participants. + +The API endpoint defined in [Chapter 4.1.2.1](#4121-api-endpoints--resources) **MUST** therefore be offered as Data Asset/Contract +Offer as defined in [[CX-0018]](#61-normative-references). + +#### 4.1.2 API SPECIFICATION + +##### 4.1.2.1 API Endpoints & Resources + +To support the exchange of Request For Quotation data, a supplier acting as a data consumer **MUST** +define a single endpoint supporting the HTTP POST request method as described in [RFC9110](#62-non-normative-references). The +structure of the endpoint **MAY** be freely chosen. The address of the endpoint **MUST** be provided +as part of the connector data asset defined in [Chapter 4.1.3](#413-connector-data-asset-structure) of this document. + +##### 4.1.2.2 Available Data Types + +The API **MUST** use JSON as the payload transported via HTTPS. + +#### 4.1.3 CONNECTOR DATA ASSET STRUCTURE + +The endpoint introduced in [Chapter 4.1.2](#412-api-specification) **MUST NOT** be called from a buyer directly. Rather, this +**MUST** be called via a connector conformant to [[CX-0018]](#61-normative-references). Therefore, the endpoint **MUST** be offered as +a connector data asset. To make this assets easily identifiable in the connector's catalog, it **MUST** be +configured with a set of properties as defined in the table below. + +| Object | Property | Purpose | Usage & Constraints +| --- | --- | --- | --- +| |***@id*** | Identifier of the asset. | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. +| properties | **`http://purl.org/dc/terms/type`** | Defines the "Request for Quotation API Endpoint" according to the Catena-X taxonomy.| **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#RequestForQuotationApi"}` to allow filtering the data assets catalog for the respective Request for Quotation API endpoint . +| properties | **`https://w3id.org/catenax/ontology/common#version`**| The version of the standard defining the implemented API.| **MUST** correspond to the version of the standard defining the "Request for Quotation API". The value **MUST** be set to `2.0` for APIs implementing this standard. +| dataAddress | **@type** | Type of the DataAddress node.| **MUST** be set to "`DataAddress`". +| dataAddress | ***baseUrl*** | Defines the HTTPS endpoint of the corresponding "Request for Quotation API Endpoint". | The `{{REQUEST_FOR_QUOTATION_API_ENDPOINT}}` refers to an URL under which the API endpoint is available. HTTPS transport protocol **MUST** be used. +| dataAddress | ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body.| **MUST** be set to `"true"` to allow the API endpoint to receive a HTTPS body via the HTTPS request. +| dataAddress | ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method.| **MUST** be set to `"true"` to allow the API endpoint to also receive POST requests. +| dataAddress | ***type*** | Defines the type of data plane extension handling the data exchange.| **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. + +When searching the data assets catalog of a data consumer (MaaS supplier), a data provider (MaaS buyer) +**SHOULD** use the following properties AND their values to identify the data asset specifying the +Request for Quotation API endpoint described in [Chapter 4.1.2](#412-api-specification). + +| Property | Value +| ---------------------------------------- | --------------------------------- +| properties.***dct:type*** | `{"@id": "https://w3id.org/catenax/taxonomy#RequestForQuotationApi"}` + +The API version described in this standard document **MUST** be published in the in the property +`https://w3id.org/catenax/ontology/common#version` as version `2.0` in the asset. The requester of an +asset **MUST** be able to handle multiple assets for this endpoint, being differentiated only by the +version. The requester **SHOULD** choose the asset with the highest compatible version number +implemented by themselves. If the requester cannot find a compatible version with their own, the +requester **MUST** terminate the data transfer." + +An example connector data asset definition is given below. + +> Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "dct": "https://purl.org/dc/terms/" + }, + "@id": "{{REQUEST_FOR_QUOTATION_API_ASSET_ID}}", + "properties": { + "dct:type": { + "@id": "cx-taxo:RequestForQuotationApi" + }, + "cx-common:version": "2.0", + "description": "Request for Quotation API Endpoint" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "proxyBody": "true", + "proxyMethod": "true", + "baseUrl": "{{REQUEST_FOR_QUOTATION_API_ENDPOINT}}" + } +} +``` + +#### 4.1.4 ERROR HANDLING + +The API endpoint defined in [Chapter 4.1.2.1](#4121-api-endpoints--resources) **MUST** respond to incoming requests with HTTP status +codes as described in [RFC9110](#62-non-normative-references). All of the following HTTP status codes, except for codes `200` and +`201`, **MUST** be interpreted as failures. Therefore, it may be sufficient for a business +application to simply check if the status code is `200` or `201` or not. If not, the request failed. + +| HTTP Status Code | HTTP Status Message | Description +| --- | --- | --- +| 200| OK| The request has succeeded. The RequestForQuotation has been successfully processed in the backend system. +| 201| Created| The request has succeeded and has led to the creation of a new RequestForQuotation in the backend system. +| 400| Bad request| The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). +| 401| Unauthorized|| +| 403| Forbidden| The RequestForQuotation in question is not available for the client (e.g. it belongs to a different company) +| 405| Method not allowed | The method used to request the data was not POST +| 422| Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors, e.g. the JSON payload could not be parsed. +| 502| Service Unavailable || + +If one `RequestForQuotation` aspect is transmitted in one HTTP request, the return codes **MUST** be +used as stated in the table above. + +If a list of multiple `RequestForQuotation` aspects is transmitted in one HTTP request, the status +code `400` **MUST** be used if at least one `RequestForQuotation` in the list cannot be processed. +Applications **MAY** choose to process valid entries from a list which also contains invalid +entries. If a list of multiple `RequestForQuotation` aspects is transmitted in one HTTP request, and +all of them can be processed successfully, the status code `200` **MUST** be used. + +The return codes `401`, `405`, `422` and `503` in the table above **MAY** also be applicable to a list of +multiple `RequestForQuotation` aspects. + +Further status codes may be included in a later revision of this standard. The ability to send and +receive one status code per sent or received list item might be included in a later revision of this +standard. + +#### 4.1.5 Data Exchange + +The `RequestForQuotation` data **MUST** be sent from the buyer to the supplier using an HTTP POST +request. The data format described here **MUST** be followed for the exchange of the information needed +for quotation. + +Multiple `RequestForQuotation` aspects **MAY** be sent in one transfer as a JSON list. If only one +`RequestForQuotation` aspect is transmitted, it **MUST** still be sent as a list with one entry. + +The serialized JSON **MUST NOT** be larger than 15 MiB in size. + +The `RequestForQuotation` endpoint **MUST** be implemented by all participants who wish to participate +in Catena-X MaaS as a supplier. Buyers **MUST** be able to send requests for quotations and the +therefore needed information to the suppliers. + +The data payload itself **MUST** be a valid JSON string. + +All attributes marked as mandatory in RFQ aspect model **MUST** be included in the dataset. +Attribute marked as ' Optional' can be included in the data set. + +The usage of the attributes in the data model **MUST** follow the attribute descriptions in the +definitions of the RFQ aspect model. + +## 5 PROCESSES + +> *This section is* *normative* + +Not applicable. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is* *normative* + +| **Number** | **Standard** | **Version** +| --- | --- | --- +| [CX-0001] | EDC Discovery API | 1.0.2 +| [CX-0003] | SAMM Aspect Meta Model | 1.1.0 +| [CX-0006] | Registration and initial onboarding | 2.0.0 +| [CX-0010] | Business Partner Number (BPN) | 2.0.0 +| [CX-0018] | Dataspace Connectivity | 3.0.0 +| [CX-0115] | Manufacturing Capability Exchange | 1.0.0 +| [CX-0142] | Shop Floor Information Service | 1.0.0 + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +| **Context** | **Link** +| --- | --- +| [CX-OMW] | Catena-X Operating Model Whitepaper. Download from: https://catena-x.net/fileadmin/user_upload/Publikationen_und_WhitePaper_des_Vereins/CX_Operating_Model_Whitepaper_02_12_22.pdf +| [CX-ODRL] | Catena-X ODRL Profile repository: https://github.com/catenax-eV/cx-odrl-profile +| [ISO8601] | ISO 8601: Date and time format +| [RFC2119] | Bradner, S. Key words for use in RFCs to Indicate Requirement Levels. Available online: https://datatracker.ietf.org/doc/html/rfc2119 +| [RFC8174] | Leiba, B. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. Available online: https://datatracker.ietf.org/doc/html/rfc8174 +| [RFC9110] | HTTP Semantics (https://www.rfc-editor.org/rfc/rfc9110) +| [SMT] | How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_1.svg b/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_1.svg new file mode 100644 index 000000000..9125518cd --- /dev/null +++ b/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_1.svg @@ -0,0 +1,4 @@ + + + +
    Catena-X Core Service Provider
    Catena-X Core Service Provider
    IAM
    IAM
    Credential
    Service
    Credential...
    Keycloak
    Keycloak
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
    Data Consumer (MaaS Supplier)
    Data Consumer (MaaS Supplier)
    Connector (e.g. Tractus-X EDC)
    Connector (e.g. Trac...
    Busines Application
    Busines Application
    Request for Quotation API
    Request for Quotatio...
    Data Provider (MaaS Buyer)
    Data Provider (MaaS Buyer)
    Connector (e.g. Tractus-X EDC)
    Connector (e.g. Trac...
    Busines Application
    Busines Application
      Request for Quotation  
      Request for Quotation  
    Data Space Connectivity Communication
      (Catalog / Contracting / Transfer)  
    Data Space Connectivity Communication...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_2.svg b/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_2.svg new file mode 100644 index 000000000..55810adb1 --- /dev/null +++ b/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_2.svg @@ -0,0 +1,4 @@ + + + +
    RFQ-Identification
    RFQ-Identification
    rfqSource
    string
    rfqSource...
    rfqId
    string
    rfqId...
    rfqName
    string
    rfqName...
    rfqDateTime
    dateTime
    rfqDateTime...
    rfqVersion
    string
    rfqVersion...
    RFQ-Configuration
    RFQ-Configuration
    cadFile
    FileData
    cadFile...
    parts
    list of partObject
    parts...
    orderQuantity
    Quantity
    orderQuantity...
    lastDeliverydate
    date
    lastDeliverydate...
    firstDeliveryDate
    date
    firstDeliveryDate...
    additionalComments
    string
    additionalComments...
    additionalFiles
    list of FileData
    additionalFiles...
    RFQ-Sender
    RFQ-Sender
    senderName
    string
    senderName...
    senderAddres
    string
    senderAddres...
    senderCompanyName
    string
    senderCompanyName...
    senderEMail
    string
    senderEMail...
    senderPhoneNumber
    string
    senderPhoneNumber...
    senderAccountAdsress
    string
    senderAccountAdsress...
    senderDeliveryAddress
    string
    senderDeliveryAddres...
    senderDeliveryRequirements
    string
    senderDeliveryRequir...
    PartObject
    PartObject
    partId
    string
    partId...
    partName
    string
    partName...
    material
    MaterialData
    material...
    manufacturingDomain
    string
    manufacturingDomain...
    billOfProcess
    BillOfProcess
    billOfProcess...
    generalTolerance
    string
    generalTolerance...
    additionalRequirements
    string
    additionalRequiremen...
    partQuantity
    Quantity
    partQuantity...
    MaterialData
    MaterialData
    materialPropterties
    list of Property
    materialPropterties...
    materialFamily
    string
    materialFamily...
    BillOfProcess
    Reference to shared.bill_of_process
    BillOfProcess...
    Property
    Property
    propertyName
    string
    propertyName...
    value
    string
    value...
    valueType
    string
    valueType...
    Quantity
    Quantity
    quantityNumber
    float
    quantityNumber...
    measurementUnit
    string
    measurementUnit...
    FileData
    FileData
    fileObject
    file
    fileObject...
    fileName
    string
    fileName...
    filePath
    string
    filePath...
    fileType
    string
    fileType...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_3.svg b/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_3.svg new file mode 100644 index 000000000..88357f359 --- /dev/null +++ b/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_3.svg @@ -0,0 +1,4 @@ + + + +
    BillOfProcess
    BillOfProcess
    VersionCharacteristic
    version
    VersionCharacteristi...
    String
    billOfProcessIdentifer
    String...
    String
    productName
    String...
    String
    productVersion
    String...
    List<ProcessStep>
    process
    List<ProcessStep>...
    ProcessStep
    ProcessStep
    String
    processStepIdentifier
    String...
    String
    capabilityReference
    String...
    List<Parameter>
    inputParameters
    List<Parameter>...
    List<PrecedenceElements>
    precedenceRelation
    List<PrecedenceElemen...
    List<ProcessStepIdentifier>
    childProcessStep
    List<ProcessStepIdent...
    Enum
    processStepType
    Enum...
    List<Parameter>
    outputParameters
    List<Parameter>...
    Parameter
    Parameter
    String
    name
    String...
    String
    value
    String...
    List<String>
    semanticReference
    List<String>...
    List<ValueRange>
    valueRangeList
    List<ValueRange>...
    Enum
    parameterKey
    Enum...
    PrecedenceElements
    PrecedenceElements
    PrecedenceElement
    PrecedenceElement
    List<PrecedenceElement>
    precedenceElements
    List<PrecedenceElement>...
    List<ProcessStepIdentifier>
    successor
    List<ProcessStepIdentifie...
    Enum
    processStepType
    Enum...
    IsFirstElement
    IsLastElement
    IsProcessElement
    IsSubProcessElement
    IsFirstElement...
    TolerancesEntity
    tolerances
    TolerancesEntity...
    Enum
    parameterKey
    Enum...
    HasValue
    HasNoValue
    HasValueRange
    HasTolerances
    HasValue...
    ValueRange
    ValueRange
    String
    name
    String...
    String
    lowerValue
    String...
    String
    upperValue
    String...
    TolerancesEntity
    TolerancesEntity
    String
    name
    String...
    String
    lowerLimit
    String...
    String
    upperLimit
    String...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_4.puml b/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_4.puml new file mode 100644 index 000000000..4a309bb55 --- /dev/null +++ b/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_4.puml @@ -0,0 +1,17 @@ +@startuml Figure_4 +autonumber +skinparam sequenceMessageAlign center + +box "Data Provider" +participant "Business\nApplication" as app_prov +end box + +box "Data Consumer" +participant "Business\nApplication" as app_cons +end box + +app_prov -> app_cons: Send "Request for Quotation" +note right: Request for Quotation Endpoint +return Created + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_4.svg b/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_4.svg new file mode 100644 index 000000000..4e9ee8fe2 --- /dev/null +++ b/docs/standards/CX-0129-RequestforQuotationExchange/assets/Figure_4.svg @@ -0,0 +1,27 @@ +Data ProviderData ConsumerBusinessApplicationBusinessApplicationBusinessApplicationBusinessApplication1Send "Request for Quotation"Request for Quotation Endpoint2Created \ No newline at end of file diff --git a/docs/standards/CX-0131-CircularityCore/CX-0131-CircularityCore.md b/docs/standards/CX-0131-CircularityCore/CX-0131-CircularityCore.md new file mode 100644 index 000000000..cecb51c88 --- /dev/null +++ b/docs/standards/CX-0131-CircularityCore/CX-0131-CircularityCore.md @@ -0,0 +1,852 @@ +# CX-0131 Circularity Core v1.1.0 + +## ABSTRACT + +This standards concludes the [Circularity KIT](https://eclipse-tractusx.github.io/docs-kits/kits/Circularity_KIT/page-adoption-view/) and shall empower stakeholders to transition towards a circular economy by providing frameworks, guidelines and best practices to enhance sustainability credentials, enable data-driven decision-making and foster collaboration and innovation in the automotive industry. +Secondary Material Content (SMC), Material Accounting (MA), End-of-Life (EoL) and Dismantling Services, and the CE-Assistant are the four focus topics that form the first version of the Circularity KIT. The offered content and artifacts address important use cases such as sustainable material management, waste minimization and resource efficiency, that contribute to more sustainable and circular automotive value loops. +The overarching goals are: + +- Establish an understanding of requirements along circular value chains and how businesses can profit by implementing sustainable solutions +- Offer standards and guidelines for industry stakeholders +- Create the basis for data exchange and applications to ensure the provided frameworks are used in the intended way +- Explain different circularity topics and provide tools to implement them + +## 1. INTRODUCTION + +Within Circular Economy (CE) it is of utmost importance that any of the partners in the supply chain work closely together and share relevant information that they can provide. Due to the loops in the supply chain the role allocation of suppliers and customers is not as clear as in linear economy. Therefore, it is crucial within Circular Economy to understand the processes, conditions, connections, transitions, and temporal aspects of materials, parts, and vehicles. This involves navigating the complexities of End-of-Life (EoL) considerations, CE-Assistant, Material Accounting (MA), and Secondary Material Content (SMC). Efficiently managing resources and strategically addressing end-of-life phases are integral to fostering sustainability in a closed-loop system. + +### 1.1 AUDIENCE & SCOPE + +*This section is non-normative* + +List for which roles the standard is relevant: + +- Data Provider / Consumer +- Business Application Provider + +The standard is of interest to all members of the automotive supply chain including suppliers, OEMs, dismantlers, recyclers and stakeholders within the recycling industry and the CE. + +Additionally, the standards also apply to software providers and core service providers to ensure interoperability and data sovereignty between different core service providers. The scope of this document is to provide guidance about the different standards in the Circularity use case. + +### 1.2 CONTEXT + +In order to effectively enhance circularity along the supply chain, standardized approaches to different aspects of circular economy are essential. This covers the usage of SMC, MA, the CE-Assistant as well as the complexities of EoL Services. The standardization provides structured frameworks based on which information can be shared across industries and stakeholders. Therefore, it enhances comparability between companies and, by reducing the chance of misunderstandings, increases data quality. + +In the EoL the issuence of a `Certificate of Decommissioning` (CoDM) by an authorized dismantling company classifies a vehicle and all associated components as EoL. The issuance of the certificate is exclusively handled by a company within Catena-X holding the CX-verifiable credential `Dismantler`. Therefore, the CoDM consistently marks the end of the initial life cycle phase of an asset, initiating the EoL process. Subsequently, additional certificates provide the opportunity to commence the start of a component's second or n-th life. However, a vehicle with a specific VIN is unequivocally designated as EoL. The End-of-Life-Vehicle (ELV) will be consecutive dismantled. + +The CE-Assistant can then be used to support the dismantling company in its decision as to which components of the ELV should be reused, refurbished, remanufactured or recycled. The assistant suggests the most environmental friendly R-strategy for the components. The asset/part/component/material/fluid/etc. must be certified - reuse, repair, remanufacturing, refurbishment, material recycling, waste - in accordance with the decision made by the stakeholder of concern. This certification makes it possible to track the life cycle of the components precisely. It also offers the advantage of being able to keep statistics on what percentage of its components have been allocated to which R-strategy. In the evaluation of the carbon dioxide (CO2) emissions of different components and their subsequent integration into the digital twin (DT), the precise categorization of these component's across different life cycle phases is a central factor. + +The utilization of precisely defined EoL certificates enables the accurate determination of a components current life cycle phase. This precision not only ensures a reliable assessment, but also facilitates a comprehensive understanding of the environmental impact and carbon footprint of the components, seamlessly integrating this valuable information into the digital twin framework. The dismantling process is carried out in accordance with all legal requirements (e.g. documentation of pollutant removal, etc.). The vehicle is then dismantled and individual materials are separated. + +The separated assets are part of further processing by any R-strategy. The second life of the asset might for example be Reuse, Repair, Remanufacture or Recycle. Depending on the exact R-Strategy, different data might be interesting for the second life of the asset. + +MA provides standardized scrap/waste and secondary material data exchange for the ecosystem partners to create transparency about recycling activities and verifiable closed loops. + +To close the loops and to understand the usage of the materials provided through the previous steps, SMC explores ways to incorporate secondary materials into the value chain. By facilitating a standardized data model for data exchange and introducing a calculation methodology, this framework establishes a foundation to facilitate communication between stakeholders. Through this, the secondary materials are being brought back into the loop. +Those materials are processed into new products and after entering the EoL-phase the loop is closed. + +### 1.3 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +### 1.4 PROOF OF CONFORMITY + +All participants and their solutions will need to proof, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). Please refer to the [certification information page](https://catena-x.net/en/catena-x-introduce-implement/certification) for the process of conformity assessment and certification. Since this Core document describes a set of standards to be fulfilled, participants **MUST** fulfill all mentioned standards for the relevant sub-usecase ([2.3](#23-secondary-material-content), [2.4](#24-eol-services), [2.5](#25-ce-assistant)) and the respective conformity assessment criteria in addition to the specific criteria mentioned in this document. The specific criteria described in this document are describing the usage of the central tools as well as common tools described in the linked standardization documents and therefore compliance should be checked with the tools provided for these components. + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +All usecase relevant terminologies can be found in the [circularity kit](https://eclipse-tractusx.github.io/docs-kits/kits/Circularity_KIT/page-adoption-view) + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2. STANDARDS FOR CIRCULARITY CORE + +> *This section is normative* + +### 2.1 Overall Standalone Standards + +- CX-0001:1.0 EDC Discovery API +- CX-0002:2.2 Digital Twin in Catena-X +- CX-0003:1.1 SAMM Semantic Aspect Meta Model +- CX-0006:2.0 Registration And Initial OnBoarding +- CX-0013:2.0 Identity of Member Companies +- CX-0014:1.0 Employees and Technical Users +- CX-0015:1.0 IAM & Access Control Paradigm +- CX-0018:3.0 Dataspace Connectivity +- CX-0049:2.0 DID Document Schema +- CX-0050:2.0 Framework Agreement Credential + +### 2.2 General Requirements + +#### 2.2.1 Conventions for Use Case and Core (this document) Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository. This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +#### 2.2.2 Additional Details regarding Access Policies + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +#### 2.2.3 Additional Details regarding Usage Policies + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies MAY include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODLR policy rule values to be used for the above-mentioned types are provided via the ODRL policy repository. + +#### 2.2.4 Onboarding and IAM + +All participants mentioned under 1.1 **MUST** follow the CX Standards [CX-0006](https://catena-x.net/en/standard-library) and [CX-0013](https://catena-x.net/en/standard-library) to [CX-0017](https://catena-x.net/en/standard-library). + +#### 2.2.5 Fetching EDC Endpoints + +To find the EDC Endpoint addresses of related parties in Catena-X, app provider **MUST** follow the [CX-0001](https://catena-x.net/en/standard-library) Standard. + +#### 2.2.6 Searching for Decentralized Digital Twin Registries + +To find decentralized Digital Twin Registries of related parties in Catena-X, app provider **MUST** follow the [CX-0002](https://catena-x.net/en/standard-library) Standard. + +#### 2.2.7 Registration at the BPN Discovery Service + +To find the Business Partner Number of the related parties in Catena-X, data provider (Only relevant for the sub use cases [2.4](#24-eol-services), [2.5](#25-ce-assistant)) **MUST** follow the [CX-0053:2.1](https://catena-x.net/en/standard-library) standard. + +Example can be found in the [Digital Twin Kit](https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/dt-kit-software-development-view) + +### 2.3 Secondary Material Content + +#### 2.3.1 LIST OF STANDALONE STANDARDS SMC + +To participate in the Secondary Material Content sub-use case, the following single standards **MUST** be fulfilled by all participants mentioned under [1.1](#11-audience--scope), if data is provided: + +- [Aspect Model SecondaryMaterialContent v1.0](#323-aspect-model-secondarymaterialcontent) + +#### 2.3.2 DATA REQUIRED + +If data is provide, Data Provider **MUST** provide a *PartAsPlanned* or a *PartAsBuilt* together with the aspect for *SecondaryMaterialContent*. + +#### 2.3.3 ADDITIONAL REQUIREMENTS + +##### 2.3.3.1 Registration of the Digital Twin and the SMC Submodel in the Digital Twin Registry + +Specific asset IDs **MUST** be provided when registering a digital twin: + +- For AsPlanned: ``ManufacturerPartID`` & ``"assetLifecyclePhase=AsPlanned"`` +- For AsBuilt: ``PartInstanceID`` & ``"assetLifecyclePhase=AsBuilt"`` + +See the following example: + +```json + "specificAssetIds": [ + { + "key": "manufacturerPartId", + "value": "{{manufacturerPartId}}", + }, + { + "key" : "assetLifecyclePhase", + "value": "AsPlanned" + } + ] +``` + +- The data provider also **MUST** provide an API Endpoint following the [CX-0002](#21-overall-standalone-standards). +- Data provider **MUST** register the related SMC sub-model as shown in the example below. +- The ``subprotocolBody`` definition **MUST** follow [CX-0002](#21-overall-standalone-standards) +- The id added to the subprotocolBody **SHOULD** be a UUIDv4 +- The ``href`` definition follows [CX-0002](#21-overall-standalone-standards). + +##### 2.3.3.2 EDC Asset Structure + +The asset structure **MUST** follow the CX-Standard [0018](#21-overall-standalone-standards). For examples we recommend to use the official [connector kit](https://eclipse-tractusx.github.io/docs-kits/kits/tractusx-edc/docs/samples/management-api-v2-walkthrough/assets) + +##### 2.3.3.3 EDC Contract Definition + +The contract definition **MUST** follow the CX-Standard [0018](#21-overall-standalone-standards). For examples we recommend to use the official [connector kit](https://eclipse-tractusx.github.io/docs-kits/kits/tractusx-edc/docs/samples/management-api-v2-walkthrough/contract-definitions) + +### 2.4 EoL Services + +#### 2.4.1 LIST OF STANDALONE STANDARDS EoL Services + +To participate in the EoL Services use-case, the following single standards are **RECOMMENDED** to be fulfilled by all participants for which the standard is relevant: + +- CX-0127:2.0 Industry Core: Part Instance with the Aspect Model "SerialPart" +- CX-0127:2.0 Industry Core: Part Instance with the Aspect Model "SingleLevelBoMAsBuilt" +- CX-0126:2.0 Industry Core: Part Type with the Aspect Model "SingleLevelBomAsPlanned" +- [Aspect Model SingleLevelBoMAsSpecified v2.0.0](#31-aspect-model-singlelevelbomasspecified) +- [Aspect Model MaterialForHomologation v1.0.0](#32-aspect-model-materialforhomologation) +- [Aspect Model PartAsSpecified v1.0.1](#33-aspect-model-partasspecified) +- [Aspect Model QualityTask v1.0.2](#34-aspect-model-qualitytask) +- [Aspect Model VehicleProductDescription v2.0.0](#35-aspect-model-vehicleproductdescription) +- [Aspect Model FleetDiagnosticData](#36-aspect-model-fleetdiagnosticdata) +- [Aspect Model FleetClaimData v1.0.1](#37-aspect-model-fleetclaimdata) +- [Aspect Model PartAnalyses v2.0.0](#38-aspect-model-partanalyses) +- [Aspect Model ManufacturedPartsQualityInformation v1.0.1](#39-aspect-model-manufacturedpartsqualityinformation) +- [Aspect Model FleetVehicles v1.0.0](#310-aspect-model-fleetvehicles) +- [Aspect Model QualityTaskAttachment v1.0.0](#311-aspect-model-qualitytaskattachment) + +Participants in the use case **MUST** follow Catena-X aligned [data models](https://github.com/eclipse-tractusx/sldt-semantic-models). + +#### 2.4.2 ADDITIONAL REQUIREMENTS + +The CX-verifiable credential “Dismantler” **MUST** be held by the issuing business partner in order to be able to issue the [Aspect Model Certificate of Decommissioning v1.0](#322-aspect-model-decommissioningcertificate) certificate. + +The business partners implementing the respective R-strategy (Reuse, Repair, Remanufacturing, Refurbishment, Material Recycling) or adding waste to the waste stream **SHOULD** issue the corresponding certificate. + +**Differentiation between reuse, remanufacturing and refurbishment of parts and components** + +For the reuse of a component or part, the following requirements **MUST** be met in accordance with the [Proposal for a REGULATION OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL on circularity requirements for vehicle design and on management of end-of-life vehicles, amending Regulations (EU) 2018/858 and 2019/1020 and repealing Directives 2000/53/EC and 2005/64/EC, Annex Part D:](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A52023PC0451). + +For the remanufacturing or refurbishment of a component or part, the following requirements **MUST** be met in accordance with the [Proposal for a REGULATION OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL on circularity requirements for vehicle design and on management of end-of-life vehicles, amending Regulations (EU) 2018/858 and 2019/1020 and repealing Directives 2000/53/EC and 2005/64/EC, Annex Part D:](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A52023PC0451). + +Application Provider for EoL Services **MUST** be able to handle the following certificates: + +- [Aspect Model Certificate of Decommissioning v1.0](#322-aspect-model-decommissioningcertificate) +- [Aspect Model Reuse Certificate v3.0](#316-aspect-model-reusecertificate) +- [Aspect Model Waste Certificate v1.0](#317-aspect-model-wastecertificate) +- [Aspect Model Refurbishing Certificate v3.0](#318-aspect-model-refurbishingcertificate) +- [Aspect Model Remanufacturing Certificate v3.0](#319-aspect-model-remanufacturingcertificate) +- [Aspect Model Material Recycling Certificate v1.0](#320-aspect-model-materialrecyclingcertificate) +- [Aspect Model Repair Certificate v1.0.0](#321-aspect-model-repaircertificate) + +##### 2.4.2.1 Registration of the Digital Twin and the Submodel in the Digital Twin Registry + +Digital twins **MUST** be registered by a data provider participating in the sub use case EoL Services, if data is available, for `Vehicles` and every part that is subject to R-Strategies. + +A data provider **MUST** register their AAS of the respective certificate as following: + +- Certificate of Decommissioning: ``CoDM_{{PartinstanceId}}`` +- Reuse Certificate: ``reuseCrt_{{PartInstanceId}}`` +- Repair Certificate: ``repairCrt_{{PartInstanceId}}`` +- Remanufacturing Certificate: ``remanCrt_{{PartInstanceId}}`` +- Refurbishing Certificate: ``refurbCrt_{{PartInstanceId}}`` +- Material Recycling Certificate: ``matrecCrt_{{PartInstanceId}}`` +- Waste Certificate: ``wasteCrt_{{PartInstanceId}}`` + +By issuing the CoDM, all Parts of the vehicle **MUST** be registered as ``CoDM_{{PartinstanceId}}``. When issuing one of the following certificates Reuse, Remanufacturing, Refurbishing, Material Recycling or Waste, the respective issued certificate **MUST** be added to the respective AAS. + +A Data Provider MUST add the specific BPN-L as externalSubjectId to grant access to the specificAssetId partInstanceId + +Additionally, depending on the lifecycle, the following asset IDs **MUST** be provided: + +- For AsPlanned: ``ManufacturerPartID`` & ``"assetLifecyclePhase=AsPlanned"`` +- For AsBuilt: ``PartInstanceID`` & ``"assetLifecyclePhase=AsBuilt"`` +- For the ``CustomerPartID"`` a external ``externalSubjectId`` a BPN **MUST** be set. + +- A data provider also **MUST** provide a API Endpoint following the [CX-0002](#21-overall-standalone-standards). +- A Data provider **MUST** register the related certificate sub-models. +- The ``subprotocolBody`` definition MUST follow [CX-0002](#21-overall-standalone-standards) +- The id added to the subprotocolBody **SHOULD** be a UUIDv4 +- The ``href`` definition follows [CX-0002](#21-overall-standalone-standards). + +##### 2.4.2.2 EDC Asset Structure for EoL Services + +The asset structure **MUST** follow the CX-Standard [0018](#21-overall-standalone-standards). For examples we recommend to use the official [connector kit](https://eclipse-tractusx.github.io/docs-kits/kits/tractusx-edc/docs/samples/management-api-v2-walkthrough/assets) + +##### 2.4.2.3 EDC Contract Definition for EoL Services + +The contract definition **MUST** follow the CX-Standard [0018](#21-overall-standalone-standards). For examples we recommend to use the official [connector kit](https://eclipse-tractusx.github.io/docs-kits/kits/tractusx-edc/docs/samples/management-api-v2-walkthrough/contract-definitions) + +##### 2.4.2.4 EDC Policy Structure for EoL Services + +For the sub use case EoL Services the condition mentioned under [2.6](#26-edc-policy-structure) MUST be fulfilled. In addition the application **MUST** verify the presence of the dismantler credential (see [CX-0131](#2-standards-for-circularity-core)) before attaching the certificate to the twin. Prior to issuing a certificate, it is necessary to check whether a certificate has already been issued for this asset. If this is the case, it should be indicated to the issuing party. + +**Example:** + +```json +{ + "constraint": { + "leftOperand": "Dismantler.activityType", + "operator": "eq", + "rightOperand": "vehicleDismantle" + } +} +``` + +### 2.5 CE-Assistant + +#### 2.5.1 LIST OF STANDALONE STANDARDS + +To participate in the CE-Assistant use-case, the following single standards are **RECOMMENDED** to be fulfilled by all participants for which the standard is relevant: + +- CX-0127:2.0 Industry Core: Part Instance with the Aspect Model "SingleLevelBoMAsBuilt" +- CX-0127:2.0 Industry Core: Part Instance with the Aspect Model "Batch" +- CX-0126:2.0 Industry Core: Part Type with the Aspect Model "PartType" +- CX-0136:1.0 Use Case PCF + +To participate in the CE-Assistant use-case, compliance to the following data models is **RECOMMENDED** by all participants for which the standard is relevant: + +- [Aspect Model SingleLevelBoMAsSpecified](#31-aspect-model-singlelevelbomasspecified) +- [Aspect Model MaterialForHomologation](#32-aspect-model-materialforhomologation) +- [Aspect Model PartAsSpecified](#33-aspect-model-partasspecified) +- [Aspect Model ReturnRequest](#312-aspect-model-returnrequest) +- [Aspect Model BatteryPass](#313-aspect-model-batterypass) +- [Aspect Model Marketplaceoffer](#314-aspect-model-marketplaceoffer) +- [Aspect Model VehicleProductDescription](#35-aspect-model-vehicleproductdescription) +- [Aspect Model PartAnalyses](#38-aspect-model-partanalyses) +- [Aspect Model ManufacturedPartsQualityInformation](#39-aspect-model-manufacturedpartsqualityinformation) +- [Aspect Model RemainingUsefulLife](#315-aspect-model-remainingusefullife) +- [Aspect Model QualityTaskAttachment](#311-aspect-model-qualitytaskattachment) + +To participate in the CE-Assistant use-case, compliance to the following data models / certificates is **RECOMMENDED** by all participants for which the standard is relevant: + +- [Aspect Model Reuse Certificate v3.0](#316-aspect-model-reusecertificate) +- [Aspect Model Refurbishing Certificate v3.0](#318-aspect-model-refurbishingcertificate) +- [Aspect Model Remanufacturing Certificate v3.0](#319-aspect-model-remanufacturingcertificate) +- [Aspect Model Repair Certificate v1.0.0](#321-aspect-model-repaircertificate) + +#### 2.5.2 DATA REQUIRED for CE Assistant + +Currenty there are no data models that are mandatory to be used. + +#### 2.5.3 ADDITIONAL REQUIREMENTS + +##### 2.5.3.1 Registration of the Digital Twin and the Submodel in the Digital Twin Registry + +Digital Twins **MUST** be registered in the decentralized digital twin registry. For looking up the twin ID for *vehicles*, the data provider **MUST** register the twins with the ``specificAssetIds: VIN`` and ``assetLifecyclePhase= AsBuild``. + +```json +"specificAssetIds": [ + { + "key": "VIN", + "value": "{{VIN}}", + }, + { + "key" : "assetLifecyclePhase", + "value": "AsBuild", + } + ] +``` + +Digital Twins **MUST** be registered in the decentralized digital twin registry. For looking up the twin ID for **components**, the data provider **MUST** register the twins with the ``specificAssetIds: manufacturerPartID`` and ``assetLifecyclePhase= AsPlanned``. + +For components: + +```json +"specificAssetIds": [ + { + "key": "manufacturerPartId", + "value": "{{manufacturerPartId}}", + }, + { + "key" : "assetLifecyclePhase", + "value": "AsPlanned", + } + ] +``` + +- The data provider also **MUST** provide a API Endpoint following the [CX-0002](#21-overall-standalone-standards). +- Data provider **MUST** register the related C sub-model as shown in the example below. +- The ``subprotocolBody`` definition **MUST** follow [CX-0002](#21-overall-standalone-standards) +- The id added to the subprotocolBody **SHOULD** be a UUIDv4 +- The ``href`` definition follows [CX-0002](#21-overall-standalone-standards). + +The data provider also **MUST** provide an API Endpoint following [CX-0002](#2-standards-for-circularity-core). + +##### 2.5.3.2 EDC Asset Structure for CE Assistant + +The asset structure **MUST** follow the CX-Standard [0018](#21-overall-standalone-standards). For examples we recommend to use the official [connector kit](https://eclipse-tractusx.github.io/docs-kits/kits/tractusx-edc/docs/samples/management-api-v2-walkthrough/assets) + +##### 2.5.3.3 EDC Contract Definition for CE Assistant + +The contract definition **MUST** follow the CX-Standard [0018](#21-overall-standalone-standards). For examples we recommend to use the official [connector kit](https://eclipse-tractusx.github.io/docs-kits/kits/tractusx-edc/docs/samples/management-api-v2-walkthrough/policy-definitions) + +##### 2.5.3.4 Components and parts not to be reused + +The following components and parts **MUST NOT** be reused in accordance with the Proposal for a [REGULATION OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL on circularity requirements for vehicle design and on management of end-of-life vehicles, amending Regulations (EU) 2018/858 and 2019/1020 and repealing Directives 2000/53/EC and 2005/64/EC, Annex Part E:](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A52023PC0451). + +For the selection of an R-Strategy of a component consider the differentiation in [2.4.2 Additional requirements](#242-additional-requirements) + +### 2.6 EDC Policy Structure + +The policies mentioned in this chapter **MUST** be fulfilled by each use case mentioned in this document as well as a participant mentioned under [1.1](#11-audience--scope) **MUST** sign the overall [Catena-X Terms and Condition](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations) +as well as the [circular economy framework agreement](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations). +This follows the first SSI setup following the [IAM Standards](#21-overall-standalone-standards) in CX covering the new SSI infrastructure which will released with release 3.2. + +The minimum set of **membership** and the **circular economy framework agreement** + +```json +{ + "@context": { + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "{{POLICY_ID}}", + "policy": { + "@type": "Policy", + "odrl:permission": [ + { + "odrl:action": "USE", + "odrl:constraint": { + "@type": "LogicalConstraint", + "odrl:and": [ + { + "@type": "Constraint", + "odrl:leftOperand": "Membership", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + }, + { + "@type": "Constraint", + "odrl:leftOperand": "FrameworkAgreement.sustainability", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + } + ] + } + } + ] + } +} +``` + +For more examples have a look [here](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md). + +## 3 ASPECT MODELS + +> *This section is normative* + +### 3.1 ASPECT MODEL "SingleLevelBoMAsSpecified" + +The SingleLevelBoMAsSpecified defines the view of the OEM or producer of the whole product, e.g. the OEM of a vehicle. It is free of any supplier-related information and specifies the promised and guaranteed content of the whole product to the end customer. This “top-down” view contrasts with the “bottom-up” view of the SingleLevelBoMAsPlanned, though several sub-aspects are shared. The SingleLevelBoMAsSpecified is merely one aspect, which is attached to the twin of the whole product and itself does neither introduce further twins nor reference them. Instead, it merely comprises all functional information required by dismantlers, workshops, or requestors for used parts to search for and to make a match on the marketplace. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.single_level_bom_as_specified:2.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.single_level_bom_as_specified/2.0.0/SingleLevelBomAsSpecified.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_specified/2.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.single_level_bom_as_specified/2.0.0/gen +``` + +### 3.2 ASPECT MODEL "MaterialForHomologation" + +The data model Material for Homologation describes the naming and classification of a material to be used in a RRR calculation according to ISO 2262. The values represent the material name, the standard that the material complies with and their respective VDA group according VDA 231-106. The VDA 231-106classification enables a reliable RRR calculation as each VDA group is is related to an ISO 2262 group. + +The semantic model has the unique identifier: + +```text + urn:bamm:io.catenax.material_for_homologation:1.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.material_for_homologation/1.0.0/MaterialForHomologation.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.material_for_homologation/1.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.material_for_homologation/1.0.0/gen +``` + +### 3.3 ASPECT MODEL "PartAsSpecified" + +The aspect model PartAsSpecified belongs to the part catalogue. A PartAsSpecified represents a certain OEM catalog part on part number level, providing a digital representation of the part as specified by the OEM. The link to the serialized part is done via the partId, this can only be done if the respective digital twins were provided by the supplier within the value chain. + +The semantic model has the unique identifier: + +```text + urn:bamm:io.catenax.part_as_specified:2.0.0# +``` + +The artifacts of the semantic model: + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.part_as_specified/2.0.0/PartAsSpecified.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_as_specified/2.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.part_as_specified/2.0.0/gen +``` + +### 3.4 ASPECT MODEL "QualityTask" + +The Quality Task data model defines the root element for Catena-X-based quality work. It describes the quality task and why two or more companies want to work collaboratively on a quality topic. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.quality_task:2.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.quality_task/2.0.0/QualityTask.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.quality_task/2.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.quality_task/2.0.0/gen +``` + +### 3.5 ASPECT MODEL "VehicleProductDescription" + +The Vehicle.ProductDescription data model is a representation of one vehicle affected by one or more QualityTask. The data model represents the vehicle when it was sold to the end-customers from an end-customers point of view: Which standard equipment was installed in the vehicle and which extra equipment was installed in the vehicle. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.vehicle.product_description:3.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.vehicle.product_description/3.0.0/ProductDescription.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.vehicle.product_description/3.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.vehicle.product_description/3.0.0/gen +``` + +### 3.6 ASPECT MODEL "FleetDiagnosticData" + +The Fleet.DiagnosticData model is one of the biggest data models from the Catena-X use case Live Quality Loops (QAX). The model can transport stationary diagnostic data that is done in a workshop, as well as diagnostic data coming from connected vehicles over-the-air. The general structure of the Fleet.DiagnosticData model is a list of diagnostic sessions. Each diagnostic session comes from a vehicle. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.fleet.diagnostic_data:2.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.fleet.diagnostic_data/2.0.0/DiagnosticData.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.fleet.diagnostic_data/2.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.fleet.diagnostic_data/2.0.0/gen +``` + +### 3.7 ASPECT MODEL "FleetClaimData" + +The Fleet.ClaimData model is used to exchange customer complaints that are recorded in a workshop: If a customer has a complaint with his car during the warranty period he goes to the workshop and wants the issue to be fixed. The data model Fleet.ClaimData allows to exchange multiple complaints with a component manufacturer at once. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.fleet.claim_data:2.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.fleet.claim_data/2.0.0/ClaimData.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.fleet.claim_data/2.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.fleet.claim_data/2.0.0/gen +``` + +### 3.8 ASPECT MODEL "PartAnalyses" + +The PartsAnalyses data model is used to exchange information about analyzed parts that were send back from the automotive manufacturer (OEM) to the part manufacturer. These analyses and their results are related to one or more quality tasks. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.parts_analyses:3.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.parts_analyses/3.0.0/PartsAnalyses.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.parts_analyses/3.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.parts_analyses/3.0.0/gen + +``` + +### 3.9 ASPECT MODEL "ManufacturedPartsQualityInformation" + +The data model ManufacturedPartsQualityInformation is a set of manufacturing-related properties of a produced part/component that could be relevant to solve a quality task. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.manufactured_parts_quality_information:2.1.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.manufactured_parts_quality_information/2.1.0/ManufacturedPartsQualityInformation.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.manufactured_parts_quality_information/2.1.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.manufactured_parts_quality_information/2.1.0/gen +``` + +### 3.10 ASPECT MODEL "FleetVehicles" + +The data model End of Life of Vehicle Compliance describes the RRR calculation results according to ISO 22628. The values represent the calculated quotas, the material masses of each fraction, the mass of the vehicle or component, the considered recycling technologies and the list of potential dismantled parts. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.fleet.vehicles:2.1.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.fleet.vehicles/2.1.0/Vehicles.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.fleet.vehicles/2.1.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.fleet.vehicles/2.1.0/gen +``` + +### 3.11 ASPECT MODEL "QualityTaskAttachment" + +The QualityTaskAttachment data model describes a way to exchange data and files, which are not available in the existing data models, in the context of a QualityTask. In order to make the non-standardized data and files machine understandable, they are described using the "Quality Task Attachment" model. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.quality_task_attachment:2.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.quality_task_attachment/2.0.0/QualityTaskAttachment.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.quality_task_attachment/2.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.quality_task_attachment/2.0.0/gen +``` + +### 3.12 ASPECT MODEL "ReturnRequest" + +The Return Request data model is used to flag a component and/or product to indicate that there is a demand or a request for return. Through this aspect, the part producer of a part specifies whether and why a he wants to receive it back. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.return_request:2.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.return_request/2.0.0/ReturnRequest.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.return_request/2.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.return_request/2.0.0/gen +``` + +### 3.13 ASPECT MODEL "BatteryPass" + +The Battery Pass provides foundations for digital infrastructures for its documentation, the exchange of basic information and update-relevant technical data – in particular, data that comprehensively describes supply-chain accountability, such as greenhouse gas footprint, working conditions in raw material extraction, or the determination of battery conditions. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.battery.battery_pass:5.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.battery.battery_pass/5.0.0/BatteryPass.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.battery.battery_pass/5.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.battery.battery_pass/5.0.0/gen +``` + +### 3.14 ASPECT MODEL "MarketplaceOffer" + +The data model "marketplace offer" includes all needed information to place a marketplace offer on a marketplace. It is in the general interest of all parties involved to be provided with the relevant information necessary to complete the transaction intended, e.g., to buy a used part from the marketplace. + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.market_place_offer:2.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.market_place_offer/2.0.0/MarketplaceOffer.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.market_place_offer/2.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.market_place_offer/2.0.0/gen +``` + +### 3.15 ASPECT MODEL "RemainingUsefulLife" + +The data model Remaining Useful Life contains the two relevant values to describe the expected remaining life of a vehicle, remaining running distance and remaining operating hours. + +The semantic model has the unique identifier: + +```text + urn:bamm:io.catenax.rul:1.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.rul/1.0.0/RemainingUsefulLife.ttl +``` + +### 3.16 ASPECT MODEL "ReuseCertificate" + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.reuse_certificate:3.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.reuse_certificate/3.0.0/ReuseCertificate.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.reuse_certificate/3.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.reuse_certificate/3.0.0/gen +``` + +### 3.17 ASPECT MODEL "WasteCertificate" + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.waste_certificate:1.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.waste_certificate/1.0.0/WasteCertificate.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.waste_certificate/1.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.waste_certificate/1.0.0/gen +``` + +### 3.18 ASPECT MODEL "RefurbishingCertificate" + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.refurbishing_certificate:3.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.refurbishing_certificate/3.0.0/RefurbishingCertificate.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.refurbishing_certificate/3.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.refurbishing_certificate/3.0.0/gen +``` + +### 3.19 ASPECT MODEL "RemanufacturingCertificate" + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.remanufacturing_certificate:3.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.remanufacturing_certificate/3.0.0/RemanufacturingCertificate.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.remanufacturing_certificate/3.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.remanufacturing_certificate/3.0.0/gen +``` + +### 3.20 ASPECT MODEL "MaterialRecyclingCertificate" + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.material_recycling_certificate:1.0.0 +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.material_recycling_certificate/1.0.0/MaterialRecyclingCertificate.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.material_recycling_certificate/1.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.material_recycling_certificate/1.0.0/gen +``` + +### 3.21 ASPECT MODEL "RepairCertificate" + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.repair_certificate:1.0.0 +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.repair_certificate/1.0.0/RepairCertificate.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.repair_certificate/1.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.repair_certificate/1.0.0/gen +``` + +### 3.22 ASPECT MODEL "DecommissioningCertificate" + +The semantic model has the unique identifier: + +```text + urn:bamm:io.catenax.decomissioning_certificate:1.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.decomissioning_certificate/1.0.0/DecommissioningCertificate.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.decomissioning_certificate/1.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.decomissioning_certificate/1.0.0/gen +``` + +### 3.23 ASPECT MODEL "SecondaryMaterialContent" + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.secondary_material_content:1.0.0# +``` + +The artifacts of the semantic model: + +``` +RDF Turtle File: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.secondary_material_content/1.0.0/SecondaryMaterialContent.ttl +JSON Schema: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.secondary_material_content/1.0.0/gen +AASX: https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.secondary_material_content/1.0.0/gen +``` + +## 4 REFERENCES + +### 4.1 NORMATIVE REFERENCES + +The circular economy concepts and solutions developed are based on that of the proposal for a REGULATION OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL on requirements for the circular design of vehicles and on the disposal of end-of-life vehicles the disposal of end-of-life vehicles, amending Regulations (EU) 2018/858 and (EU) 2019/1020 and repealing Directives 2000/53/EC and 2005/64/EC: + +### 4.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +To understand the standard, the following use case related papers can be helpful: + +- A logic to calculate an R-Strategy can be found in the paper: [End-of-life decision support to enable circular economy in the automotive industry based on digital twin data](https://www.sciencedirect.com/science/article/pii/S2212827123006091) (DOI: 10.1016/j.procir.2023.03.150) + +- An example of cross-company data exchange and data sovereignty via Catena-X for better decision-making on end-of-life vehicles can be found in this paper: [Empowering End-of-Life Vehicle Decision Making with Cross-Company Data Exchange and Data Sovereignty via Catena-X](https://www.mdpi.com/2071-1050/15/9/7187) (DOI: 10.3390/su15097187) + +- KIT // Circularity KIT + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +N/A + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0133-OnlineControlandSimulation/CX-0133-OnlineControlandSimulation.md b/docs/standards/CX-0133-OnlineControlandSimulation/CX-0133-OnlineControlandSimulation.md new file mode 100644 index 000000000..46ece70a2 --- /dev/null +++ b/docs/standards/CX-0133-OnlineControlandSimulation/CX-0133-OnlineControlandSimulation.md @@ -0,0 +1,1583 @@ +# CX-0133 Online Control and Simulation 1.1.0 + +## ABSTRACT + +The simulation results of the Catena-X partners on the lower tier level and logistics, together with data of the company's own operations are fed into the individual simulation model as input. Considering both, plannable and unforeseeable influencing factors, this simulation model is iterated through as often as necessary until an optimal production schedule is reached and a simulation result is created. Sharing of simulation results to the next tier level is the base of the collaborative simulation approach in a short-term horizon, across the complete supply chain. + +This basic data exchange is based on a real production state and current planning. Additionally, a further functionality allows to operate with potentially changed situations in production or changed requirements. So called "What-If" scenarios" can be initiated and communicated to the supply chain partners confirming the feasibility. + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +- Updated references to new versions +- Providers must ensure BPNL provisioning to OSim + +## DISCLAIMER REGARDING ONLINE CONTROL AND SIMULATION DATA EXCHANGE + +This document describes and standardizes certain data exchange business processes, data models and/or APIs in connection with Online Control and Simulation (OSim) solution based on the Catena-X data ecosystem. Nothing in this document is meant to determine the contractual terms and conditions for the purchase, supply, delivery or licensing of any products or services among the participants of the OSim data exchange. These terms and conditions are separately negotiated and agreed among suppliers and customers in individual purchase, supply or license agreements. In case of any inconsistencies with the content of this document, the provisions of individual agreements among the participants shall prevail over the content of this document. + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for: + +- Business Application Provider +- Data Provider / Consumer + +This document describes the process of exchange of simulation results as well as scenario data information. + +- The MaterialFlowSimulationResult object will be sent by OSim partner to another OSim partner on a higher tier level. OSim partner can be a producing company as well as a logistics company. Every MaterialFlowSimulationResult includes information about delivery readiness of packaged material goods, like material identifier, amount, delivery time and destination. The data provider needs to be able to create MaterialFlowSimulationResult and the receiver need to be able to interpret them. The data receiver needs to be able to use the MaterialFlowSimulationResult of lower tier partners as input for its own simulation. +- The MaterialFlowScenarioRequest object will be sent by OSim partner to another OSim partner at the next level (up and down). OSim partner can be a producing company as well as a logistics company. Every MaterialFlowScenarioRequest includes information about scenario header, scenario parameter and two simulation results - one for the initial flow and another one for the updated flow. Every simulation result includes equivalent information as the previously mentioned MaterialFlowSimulationResult object. The data provider needs to be able to create MaterialFlowScenarioRequest and the receiver need to be able to interpret them. The data receiver needs to be able to use the MaterialFlowScenarioRequest as input for its own simulation in scenario context. + +Information regarding the data models is described in Chapter [3. ASPECT MODELS](#3-aspect-models) + +Information regarding processing of this data models is described in Chapter [4. APPLICATION PROGRAMMING INTERFACES](#4-application-programming-interfaces) + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +Simulation is an important aspect of Supply Chain Management, as it allows a better precision of significance for the ability to deliver. OSim enables the exchange of simulation results between the partners extending the today’s scope of siloed simulations. + +The core business logic described in this document enables companies to share data in a sovereign way as well as to utilize a common process understanding, ensuring interoperability and enabling the involved parties to achieve the following goals: + +- Collaborative simulation over the supply chain (Basic flow) +- "What-If" triggered scenarios (Scenario flow) +- Early reaction to delivery problems +- Early response to changes in customer requirements +- Early consideration of external disturbances/events on the process +- Validation of potential changes in advance of implementation + +The following picture depict the rough architecture of OSim: + +![image2023-8-21_16-1-19.png](./assets/image2023-8-21_16-1-19.png) + +This standardization defines the data models MaterialFlowSimulationResult and MaterialFlowScenarioRequest for the Catena-X network. This standard ensures that information out of these models can be consumed through the Catena-X network by all OSim partners and ensures, that the data objects from different OSim partner can be handled and interpreted in an identical manner. + +Moreover this standardization defines the APIs requestLatestSimulationResult, receiveLatestSimulationResult, requestScenarioFeedback, receiveScenarioFeedback, pushScenarioState for processing and exchange of simulation results to ensure a consistent data exchange and data consumption through EDC between the OSim participants using the reverse proxy functionality. Thereby an identical interpretation of the data across companies is ensured. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +```text + As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes + in this specification are non-normative. Everything else in this specification is normative. + + The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** + and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] + when, and only when, they appear in all capitals, as shown here. + + All participants and their solutions will need to prove, that they are conform with the Catena-X standards. + To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +``` + +1. **Requirement for Conformity**: All participants and their respective solutions are required to demonstrate conformity to the Catena-X standards. + +1. **Validation Mechanism**: To ensure the proper adherence to these standards, Catena-X has authorized Conformity Assessment Bodies (CABs) to carry out the validation process. + +1. **Conformity Proof for Semantic Model**: The confirmation of adherence for a single semantic model follows the general rules for proving the conformity of data provided to a semantic model or the capability to utilize the associated data. + +1. **Submission Requirements**: To authenticate their conformity, participants are to submit to the conformity assessment body the following: + + - An example 'requestLatestSimulationResult' JSON generated by their solution. + - An example 'receiveLatestSimulationResult' JSON produced by their solution. + - An example 'requestScenarioFeedback' JSON produced by their solution. + - An example 'receiveScenarioFeedback' JSON produced by their solution. + - An example 'pushScenarioState' JSON produced by their solution. + - A verification that their solution can handle the example payload JSON as specified below. + +1. **Certification Process**: Should an assessee seek certification, they must produce a formal letter affirming their compliance with this standard. This letter should be signed by an individual possessing full power of attorney + +### 1.4 EXAMPLES + +#### 1.4.1 Process Examples + +##### 1.4.1.1 Basic flow + +The following example shows a basic exchange of simulation results in the OSim partner network of the manufacturing company Werk-76. + +![example.png](./assets/example.png) + +A request is made from Werk-76 to the logistics company Log-07 as to whether a newer simulation result is available. The logistics company Log-07 then transmits directly its latest simulation results to the data recipient Werk-76, filtered to the records relevant to Werk-76. In case no simulation result is currently available, Log-07 sends a dedicated return value to the data consumer. + +Note: Generally, it is up to the data provider to decide when its own simulation will be run, and with this a new simulation result will be generated. Accordingly, it is always in the hands of data consumer to ask for newer simulation results using the API described in OSim API + +Now, taking into account the values received from the direct partners (including the simulation results from LOG-07), the company Werk-76 can run a material flow simulation of its own production, check the results and repeat the simulation if necessary. Subsequently, Werk-76 releases its own simulation results so that they can be queried by the partners of the higher tier level in the supply-chain. + +##### 1.4.1.2 Scenario flow + +The following picture shows an example for one possible flow of OSim Scenario Management. In this example a supplier wants to verify the impact on his successors in case of potential stop of one manufacturing line for maintenance next Friday. + +![image-2023-11-14_11-32-9-1.png](./assets/image-2023-11-14_11-32-9-1.png) + +In scenario management, a distinction is made between 4 different types of scenarios: + +- The data flow from suppliers to customers +- The data flow from customers to suppliers +- The data flow from the logistician to the customer +- The data flow from the logistician to the supplier + +In this way every OSim network partner can initiate a "What-If" scenario. + +In the example above the request is made by a supplier, who is simulating the impact on the own production and sending a request for confirmation to the affected partner. This partner can evaluate the own impact using the simulation capabilities and send a reply to the scenario initiator. Alternatively he could also forward the scenario request to the next level in the supply chain. + +Thus, the principle of scenario management is a sequence of requests, each of which is acknowledged with confirmation. + +#### 1.4.2 Data Model + +##### 1.4.2.1 Basic Flow + +The following data set shows an example for a MaterialFlowSimulationResult which will be sent to the endpoint receiveLatestSimulationResult ( see API description [4.3 "RECEIVE LATEST SIMULATION RESULT" API](#43-receive-latest-simulation-result-api) ). + +```json +{ + "owner": { "id": "BPNL00000007OTZ3" }, + "dataQuality": 1, + "description": "Daily standard simulation", + "comment": "successful simulation", + "expirationTimestamp": "2023-03-24T09:15:24.000Z", + "runId": "0fece48b-c8d1-4180-1a9caca6d67e", + "shipments": [ + { + "handlingUnits": [ + { + "name": "Palette", + "volume": 1, + "weight": 189, + "batches": [ + { + "unitOfMeasurement": "KG", + "materialName": "KK1000GR-Gehäuse-Rot", + "quantity": 50, + "materialNumber": "KK1000GR", + "batchOrderId": "Order-0001", + "batchId": "Batch_1", + "hazardousGoods": false, + "batchExpirationTimestamp": "2023-08-22T16:00:00.000Z", + "batchNumber": "45" + } + ], + "handlingUnitId": "HUT_1", + "amount": 1 + } + ], + "shipmentId": "DE51515151", + "recipientTimestampPlanned": "2023-04-19T09:00:00.000Z", + "destination": { "id": "BPNL00000007OTZ3" }, + "recipient": { "id": "BPNL00000007OTZ4" }, + "logistics": { "id": "BPNL00000007OS0H" }, + "preceding": {}, + "splittingAllowed": true, + "destinationTimestamp": "2023-03-19T09:00:00.000Z" + } + ], + "timestamp": "2023-03-09T14:13:42.806Z" +} +``` + +##### 1.4.2.2 Scenario flow + +The following data set shows an example for a MaterialFlowScenarioRequest which will be sent to the endpoint *requestScenarioFeedback* ( see API description [4.4 "REQUEST SCENARIO FEEDBACK" API](#44-request-scenario-feedback-api) ). + +```json +{ + "materialFlowScenarioRequest": { + "scenarioSimResults": { + "resultOwnId": "916b5688-8bd8-4d7e-83b9-e0d40939274e", + "resultOwnSimRunInitial": { + "owner": {}, + "dataQuality": 0, + "description": "Please simulate asap", + "comment": "successful simulation ", + "expirationTimestamp": "2023-03-24T09:15:24.000Z", + "runId": "0fece48b-c8d1-4180-1a9caca6d67e", + "shipments": [ + { + "handlingUnits": [ + { + "name": "Palette", + "volume": 1, + "weight": 189, + "batches": [ + { + "unitOfMeasurement": "KG", + "materialName": "KK1000GR-Gehäuse-Rot", + "quantity": 50, + "materialNumber": "KK1000GR", + "materialHazardousGoods": false, + "batchOrderId": "Order-0001", + "batchId": "Batch_1", + "batchExpirationTimestamp": "2023-08-22T16:00:00.000Z", + "batchNumber": "45" + } + ], + "handlingUnitId": "HUT_1", + "amount": 1 + } + ], + "shipmentId": "DE51515151", + "recipientTimestampPlanned": "2023-04-19T09:00:00.000Z", + "destination": { "id": "BPNL00000SR7OTZ3" }, + "recipient": { "id": "BPNL00000SR7OTZ1" }, + "logistics": { "id": "BPNL00000SR7OTZ7" }, + "preceding": {}, + "splittingAllowed": true, + "destinationTimestamp": "2023-03-19T09:00:00.000Z" + } + ], + "timestamp": "2023-03-09T14:13:42.806Z" + }, + "resultOwnSimRunUpdated": { + "owner": {}, + "dataQuality": 0, + "description": "Please simulate asap", + "comment": "successful simulation ", + "expirationTimestamp": "2023-03-24T09:15:24.000Z", + "runId": "0fece48b-c8d1-4180-1a9caca6d67e", + "shipments": [ + { + "handlingUnits": [ + { + "name": "Palette", + "volume": 1, + "weight": 189, + "batches": [ + { + "unitOfMeasurement": "KG", + "materialName": "KK1000GR-Gehäuse-Rot", + "quantity": 50, + "materialNumber": "KK1000GR", + "materialHazardousGoods": false, + "batchOrderId": "Order-0001", + "batchId": "Batch_1", + "batchExpirationTimestamp": "2023-08-22T16:00:00.000Z", + "batchNumber": "45" + } + ], + "handlingUnitId": "HUT_1", + "amount": 1 + } + ], + "shipmentId": "DE51515151", + "recipientTimestampPlanned": "2023-04-19T09:00:00.000Z", + "destination": { "id": "BPNL00000SR7OTZ3" }, + "recipient": { "id": "BPNL00000SR7OTZ1" }, + "logistics": { "id": "BPNL00000SR7OTZ7" }, + "preceding": {}, + "splittingAllowed": true, + "destinationTimestamp": "2023-03-19T09:00:00.000Z" + } + ], + "timestamp": "2023-03-09T14:13:42.806Z" + } + }, + "scenarioParameter": { + "unitOfMeasurement": "KG", + "parameterScenario": "8d464b8b-6977-4952-8a22-0489067ca081", + "parameterComment": "updated Delivery Date", + "materialName": "KK1000GR-Gehäuse-Rot", + "parameterQuantityUpdated": 1, + "parameterId": "847c71e5-614a-468b-a3a0-674bf2af3004", + "materialNumber": "KK1000GR", + "parameterDeliveryDateUpdated": "2023-10-10T09:00:00.000Z", + "parameterDeliveryDateInitial": "2023-10-09T10:00:00.000Z", + "parameterOrderId": "OID-011123546", + "parameterQuantityInitial": 1 + }, + "scenarioHeader": { + "scenarioOwnerRole": "Customer", + "scenarioCreationTimestamp": "2023-10-04T09:10:00.000Z", + "scenarioExpirationTimestamp": "2023-10-07T09:10:00.000Z", + "scenarioOwner": "BPNL00000007OTZ3", + "scenarioDescription": "Changes in Delivery Date", + "scenarioId": "8d464b8b-6977-4952-8a22-0489067ca081", + "scenarioTitle": "Delivery Modification" + } + } +} +``` + +#### 1.4.3 API Examples + +##### 1.4.3.1 Example for requestLatestSimulationResult + +*requestLatestSimulationResult* is the request for simulation result. It contains the BPNS of the requesting OSim partner, the requestId as a request identifier when receiving result and the simulationRunId of the last received simulation result are given as parameter. + +The execution of the endpoint which is used as the base URL in the asset definition is done via an EDC connection. As parameters for the execution of the endpoint are sent as path parameters, they are added to the call of the endpoint at the data plane of the EDC which will forward them to the endpoint at the producer EDC and endpoint. + +Example: + +**Base URL of endpoint**: http://\{internal-server\}/requestLatestSimulationResult + +**URL executed to data plane in consumer edc**: http://\{dataplane-url\}/api/public/bpns/bbf461bf-28d5-4fc2-95fa-7697eb122f48/requestId/8d628899-3e6f-4666-91c3-74ee7ab88b2b/simulationRunId/50737df3-4237-4652-b092-1ef8649f6ca6 + +**URL executed to endpoint at receiver of request of simulation result:** http://\{internal-server\}/requestLatestSimulationResult/bpns/bbf461bf-28d5-4fc2-95fa-7697eb122f48/requestId/8d628899-3e6f-4666-91c3-74ee7ab88b2b/simulationRunId/50737df3-4237-4652-b092-1ef8649f6ca6 + +The *requestLatestSimulationResult* MUST be sent from the requestor of simulation results to the producer of simulation results using an HTTP GET request. + +##### 1.4.3.2 Example for receiveLatestSimulationResult + +Example JSON string for receiveLatestSimulationResult can be found in chapter [1.4.2.1 Basic Flow](#1421-basic-flow) + +The execution of the endpoint which is used as the base URL in the asset definition is done via an EDC connection. As parameters for the execution of the endpoint are sent as path parameters, they are added to the call of the endpoint at the data plane of the EDC which will forward them to the endpoint at the producer EDC and endpoint. + +Example: + +**Base URL of endpoint:** http://\{internal-server\}/receiveLatestSimulationResult + +**URL executed to data plane in consumer edc**: http://\{dataplane-url\}/api/public/requestId/8d628899-3e6f-4666-91c3-74ee7ab88b2b + +**URL executed to endpoint at producer of simulation result:** http://\{internal-server\}/receiveLatestSimulationResult/requestId/8d628899-3e6f-4666-91c3-74ee7ab88b2b + +The *receiveLatestSimulationResult* data MUST be sent from the provider of simulation results to the consumer of simulation results using an HTTP POST request. + +##### 1.4.3.3 Example for requestScenarioFeedback + +Example JSON string for requestScenarioFeedback can be found in chapter [1.4.2.2 Scenario flow](#1422-scenario-flow) + +The execution of the endpoint which is used as the base URL in the asset definition is done via an EDC connection. As parameters for the execution of the endpoint are sent as path parameters, they are added to the call of the endpoint at the data plane of the EDC which will forward them to the endpoint at the producer EDC and endpoint. + +Example: + +**Base URL of endpoint:** http://\{internal-server\}/requestScenarioFeedback + +**URL executed to data plane in consumer edc**: http://\{dataplane-url\}/api/public/requestId/8d628899-3e6f-4666-91c3-74ee7ab88b2b + +**URL executed to endpoint at producer of scenario feedback request:** http://\{internal-server\}/requestScenarioFeedback/requestId/8d628899-3e6f-4666-91c3-74ee7ab88b2b + +The *requestScenarioFeedback* data MUST be sent from the requestor of simulation results to the producer of simulation results using an HTTP POST request. + +##### 1.4.3.4 Example for receiveScenarioFeedback + +The execution of the endpoint which is used as the base URL in the asset definition is done via an EDC connection. As parameters for the execution of the endpoint are sent as path parameters, they are added to the call of the endpoint at the data plane of the EDC which will forward them to the endpoint at the producer EDC and endpoint. + +Example: + +**Base URL of endpoint:** http://\{internal-server\}/receiveScenarioFeedback + +**URL executed to data plane in consumer edc**: http://\{dataplane-url\}/api/public/requestId/8d628899-3e6f-4666-91c3-74ee7ab88b2b/bpns/bbf461bf-28d5-4fc2-95fa-7697eb122f48/scenarioId/8d464b8b-6977-4952-8a22-0489067ca081/feedback/Realizable + +**URL executed to endpoint at producer of simulation result:** http://\{internal-server\}/receiveScenarioFeedback/requestId/8d628899-3e6f-4666-91c3-74ee7ab88b2b/bpns/bbf461bf-28d5-4fc2-95fa-7697eb122f48/scenarioId/8d464b8b-6977-4952-8a22-0489067ca081/feedback/Realizable + +The *receiveScenarioFeedback* data MUST be sent from the provider of simulation results to the consumer of simulation results using an HTTP GET request. + +##### 1.4.3.5 Example for pushScenarioState + +The execution of the endpoint which is used as the base URL in the asset definition is done via an EDC connection. As parameters for the execution of the endpoint are sent as path parameters, they are added to the call of the endpoint at the data plane of the EDC which will forward them to the endpoint at the producer EDC and endpoint. + +Example: + +**Base URL of endpoint:** http://\{internal-server\}/pushScenarioState + +**URL executed to data plane in consumer edc**: http://\{dataplane-url\}/api/public/requestId/8d628899-3e6f-4666-91c3-74ee7ab88b2b/bpns/bbf461bf-28d5-4fc2-95fa-7697eb122f48/scenarioId/8d464b8b-6977-4952-8a22-0489067ca081/state/InRealization + +**URL executed to endpoint at receiver of scenario state:** http://\{internal-server\}/pushScenarioState/requestId/8d628899-3e6f-4666-91c3-74ee7ab88b2b/bpns/bbf461bf-28d5-4fc2-95fa-7697eb122f48/scenarioId/8d464b8b-6977-4952-8a22-0489067ca081/state/InRealization + +The *pushScenarioState* data MUST be sent from the provider of scenario state to the consumer of scenario state using an HTTP GET request. + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +Online Control and Simulation (OSim) : OSim is a Use Case in Catena-X eco system. + +Business Partner Number (BPN) : A BPN is the unique identifier of a partner within Catena-x. + +Business Partner Number (BPNL) : A BPNL is the unique identifier of a legal entity of a partner within Catena-X, e.g. a company. + +Business Partner Number (BPNS) : A BPNS is the unique identifier of a partner site within Catena-X, e.g. a specific factory of a company. + +Supplier : In the context of OSim the Supplier is the producer of goods. + +Customer : In the context of OSim the Customer is the receiver of produced goods by supplier. + +Logistician : In the context of OSim the Logistician transports the produced goods from supplier to the customer. + +OSim-Network construction and Tier-Levels : The following picture depicts a principal construction of a OSim Network from a global perspective (not to be confused with a participant perspective, which is always a limited view to the one-up and one-down levels, logistician disregarded). + +![TierLevels.png](./assets/TierLevels.png) + +It consists of many tier companies (e.g. S1..S7) on different levels (e.g. Tier-1, Tier-2, Tier-n, Tier-n+1) with logistician companies in between (e.g. L1 .. L8). Depend on the complexity of the logistics between two producers it is not excluded that more than one logistician are in the chain (e.g. L1 -> L2 or L1 -> L3 -> L4) + +- "Lower tier level" means direction in the network to the left and with this to the suppliers of the raw materials. The following terms are synonymously used with "Lower tier level": + - "Previous level" + - "Previous tier level" + - "Lower level" +- "Higher tier level" means direction to the OEM. Tier-1 is the highest tier level followed by the OEM. The following terms are synonymously used with "Higher tier level": + - "Next level" + - "Next tier level" + - "Higher level" + +Basic flow : is the exchange of material flow simulation results over the network of OSim partners from lower to the higher tiers + +Scenario flow : is the exchange of material flow simulation results related to "What-If" scenarios + +"What-If" scenario (also used as *scenario*) : Describes potentially changed situations in production or changed requirements + +MaterialFlowSimulationResult : The MaterialFlowSimulationResult is the data model, which describes the structure of the simulation result data exchanged between OSim partners. + +Note: Typically there is not only one own simulation result available in the single systems of suppliers or logisticians. For this it is RECOMMENDED to introduce in the single systems a state machine, allowing to identify the for publishing relevant status. For example: + +![MaterialFlowSimulationResult.png](./assets/MaterialFlowSimulationResult.png) + +simulationRunID : The simulationRunID is the unique identifier of a simulation result + +MaterialFlowScenarioRequest : The MaterialFlowScenarioRequest is the data model, which describes the structure of the scenario data exchanged between OSim partners requesting a scenario based simulation run. + +Aspect Model : a formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect. + +: Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model. + +: Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 "ONLINE CONTROL AND SIMULATION" + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +*The following Catena-X standards are prerequisite for the implementation of this standard and therefore MUST be considered / implemented by the relevant parties specified in each of them.* + +- *CX-0001 EDC Discovery API Version 1.0.2* +- *CX-0003 SAMM Aspect Meta Model Version 1.1.0 or 1.0.2* +- *CX-0018 Dataspace Connectivity Version 3.0.0* + +The here mentioned combinations of standards and versions apply to all following chapters. + +#### 2.1.2 DATA REQUIRED + +No additional data requirements + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +The data provider MUST be able to pass the BPNL of the data consumer from the dataspace connector to OSim (e.g. using the EDC extension `provision-additional-headers`). + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +This version of the document does not define any requirements for standardized integration and governance of digital twins. + +## 3 ASPECT MODELS + +> *This section is normative* + +### 3.1 ASPECT MODEL "MaterialFlowSimulationResult" + +The MaterialFlowSimulationResult information MUST be sent between OSim participants by HTTP request. The data format described in the chapter [3.1.5 FORMATS OF SEMANTIC MODEL](#315-formats-of-semantic-model) MUST be followed. + +The MaterialFlowSimulationResult data model MUST be implemented by all participants who wish to participate in the Catena-X OSim network as a customer, supplier or logistician. + +Companies, who participate in the Catena-X OSim Network as a supplier MUST be able to send MaterialFlowSimulationResult information. + +Companies, who participate in the Catena-X OSim Network as a customer MUST be able to receive MaterialFlowSimulationResult information. + +Companies who participate in the Catena-X Network as a supplier and as a customer MUST be able to receive and send MaterialFlowSimulationResult information. + +Companies who participate in the Catena-X Network as a logistician MUST be able to receive and send MaterialFlowSimulationResult information. + +#### 3.1.1 NORMATIVE CRITERIA + +Every data provider of simulation result data MUST provide the data conforming to the semantic model specified in this document. + +The unique identifier of the semantic model specified in this document MUST be used by the data provider to define the semantics of the data being transferred. + +Every certified business application relying on simulation result data MUST be able to consume data conformant to the semantic model specified in this document. + +Data consumers and data provider MUST comply with the license of the semantic model. + +In the Catena-X data space simulation result data MUST be requested and exchanged via a connector conformant to [CX-0018](#211-list-of-standalone-standards). + +The JSON Payload of data providers MUST be conformant to the JSON Schema as specified in this document. + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification. + +This aspect model is written in SAMM 2.0.0 as a modeling language conformant to [CX-0003](#211-list-of-standalone-standards) as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to [CX-0003](#211-list-of-standalone-standards). + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + urn:samm.io.catenax.material_flow_simulation_result:2.0.0 +``` + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + +```text + +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". + +```text + +``` + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +```text + +``` + +### 3.2 ASPECT MODEL "MaterialFlowScenarioRequest" + +The MaterialFlowScenarioRequest information MUST be sent between OSim participants by HTTP request. The data format described in the chapter [3.1.5 FORMATS OF SEMANTIC MODEL](#315-formats-of-semantic-model) MUST be followed. + +The MaterialFlowScenarioRequest data model MUST be implemented by all participants who wish to participate in the Catena-X OSim network as a customer, supplier or logistician. + +Companies, who participate in the Catena-X OSim Network as a supplier MUST be able to send MaterialFlowScenarioRequest information. + +Companies, who participate in the Catena-X OSim Network as a customer MUST be able to receive MaterialFlowScenarioRequest information. + +Companies who participate in the Catena-X Network as a supplier and as a customer MUST be able to receive and send MaterialFlowScenarioRequest information. + +Companies who participate in the Catena-X Network as a logistician MUST be able to receive and send MaterialFlowScenarioRequest information. + +#### 3.2.1 NORMATIVE CRITERIA + +Every scenario feedback requestor MUST provide the data conforming to the semantic model specified in this document. + +The unique identifier of the semantic model specified in this document MUST be used by the data provider to define the semantics of the data being transferred. + +Every certified business application relying on scenario feedback data MUST be able to consume data conformant to the semantic model specified in this document. + +Data consumers and data provider MUST comply with the license of the semantic model. + +In the Catena-X data space scenario data MUST be requested and exchanged via a connector conformant to [CX-0018](#211-list-of-standalone-standards). + +The JSON Payload of data providers MUST be conformant to the JSON Schema as specified in this document. + +#### 3.2.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification. + +This aspect model is written in SAMM 2.0.0 as a modeling language conformant to [CX-0003](#211-list-of-standalone-standards) as input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to [CX-0003](#211-list-of-standalone-standards). + +#### 3.2.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.2.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text +urn:samm:io.catenax.material_flow_scenario_request:1.0.0 +``` + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +#### 3.2.5 FORMATS OF SEMANTIC MODEL + +##### 3.2.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + +```text + +``` + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.2.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". + +```text + +``` + +##### 3.2.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +```text + +``` + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +### 4.1 API flow overview + +#### 4.1.1 Basic flow + +The scenario flow consists of two API calls: + +- *requestLatestSimulationResult* +- *receiveLatestSimulationResult* + +The MaterialFlowSimulationResult object (see the data model description in chapter [3.1 ASPECT MODEL "MaterialFlowSimulationResult"](#31-aspect-model-materialflowsimulationresult)) will be send by OSim partner to another OSim partner on a higher tier level. OSim partner can be a producing company as well as a logistics company. Every MaterialFlowSimulationResult includes information about delivery readiness of packaged material goods, like material identifier, amount, delivery time and destination. The data provider needs to be able to create MaterialFlowSimulationResult and the receiver need to be able to interpret them. The data receiver needs to be able to use the MaterialFlowSimulationResult of lower tier partners as input for its own simulation. + +The process of API communication is asynchronous and consists of two API calls: first a requestLatestSimulationResult and after that a receiveLatestSimulationResult as follows. An OSim partner of an upper level sends an API requestLatestSimulationResult to an OSim partner of the next lower level. The BPNS of the OSim partner that is to receive the simulation results is passed as a parameter. This parameter is necessary because the receiver cannot make sure that the sender of the API call is the correct recipient for the requested data, e.g. the sender could theoretically request simulation results dedicated to a competitor. + +The following process steps guarantee that only the correct partner will get their simulation results. The OSim partner of the next lower level confirms receipt of the message. It is checked if the BPNS exists, and it belongs to a OSim partner. In case the BPNS is unknown in the individual OSim-Network of the data provider, API returns a dedicated error code (see description of return codes in later chapter in this document) and no simulation result will be transferred. + +At next the data provider determines the connector endpoint for the received BPNS using the Discovery Service, select and filter the last simulation results for the requesting OSim partner and sends by calling the API receiveLatestSimulationResult the simulation results to the previously determined connector endpoint of the BPNS. + +The underlying business process is described and standardized in OSim Process & Core Business Logic. + +The following picture explains the general principals of the API interactions: + +![api-interactions.svg](./assets/api-interactions.svg) + +#### 4.1.2 Scenario flow + +The scenario flow consists of three API calls: + +- *requestScenarioFeedback* +- *receiveScenarioFeedback* +- *pushScenarioState* + +The ScenarioData object (see the data model description in chapter [3.2 ASPECT MODEL "MaterialFlowScenarioRequest"](#32-aspect-model-materialflowscenariorequest)) will be sent with requestScenarioFeedback API-function by OSim partner to another OSim partner when a scenario is initiated and feedback from affected partners is needed to confirm the readiness for scenario execution. OSim partner can be a producing company as well as a logistics company. Every ScenarioData-Object includes information about the scenario header and scenario related simulation results. + +Every scenario related simulation result consists of + +- Initial run: Basic simulation result (identical to a basic flow) and +- Updated run: Simulation result with consideration of the scenario parameters. Depend on the own role in the scenario, this can be +- a result of manual adjustments to the simulation model according to the scenario request or +- execution of a simulation run based on updated run received by predecessor. + +The data provider needs to be able to create ScenarioData and the receiver need to be able to interpret them. The data receiver needs to be able to use ScenarioData as input for its own investigation. + +The investigation can lead to forward the scenario including simulation results to the next affected partner or sending feedback to the requestor using receiveScenarioFeedback API-function. + +As soon the scenario owner has received feedback from all affected partners, he can send a scenario state update using the pushScenarioState API-function to the affected partners expressing the final decision about execution or rejection of the scenario. + +The following process steps guarantees that only the authorized partner will receive scenario requests and send feedbacks to the requestor. The receiving partner confirms receipt of messages. It is checked if the BPNS exists, and it belongs to a OSim partner. In case the BPNS is unknown in the individual OSim-Network of the data provider, API returns a dedicated error code (see description of return codes in later chapter in this document). + +At next the data provider determines the connector endpoint for the received BPNS using the Discovery Service and sends his feedback by calling the API receiveScenarioFeedback to the previously determined connector endpoint of the BPNS. + +The underlying business process is described and standardized in OSim Process & Core Business Logic. + +The following picture explains the general principals of the API interactions: + +![image-2023-8-29_11-10-24.svg](./assets/image-2023-8-29_11-10-24.svg) + +### 4.2 "REQUEST LATEST SIMULATION RESULT" API + +> *This section is normative* + +The requestLatestSimulationResult contains the request for the latest simulation result which is send from higher level partner to a partner on the next lower level. All participants participating in Catena-X OSim in the role of a consumer of simulation results MUST be able to execute the requestLatestSimulationResult API. All participants participating in Catena-X OSim in the role of a provider of simulation results MUST be able to receive and process the requestLatestSimulationResult API. + +#### 4.2.1 PRECONDITIONS AND DEPENDENCIES + +The requestLatestSimulationResult API MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the Catena-X standard [CX-0018](#211-list-of-standalone-standards). + +#### 4.2.2 API SPECIFICATION + +##### 4.2.2.1 API Endpoints & resources + +To support the exchange of requestLatestSimulationResult data, a business application MUST define a single endpoint supporting the HTTP GET request method as described in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html). The structure of the endpoint MAY be freely chosen. The address of the endpoint MUST be provided as part of the connector Data Asset defined in chapter [4.2.2.4 EDC Data Asset Structure](#4224-edc-data-asset-structure). + +##### 4.2.2.2 Data Exchange + +The *requestLatestSimulationResult* endpoint MUST be implemented by all participants who participate in the Catena-X OSIM network. Provider of simulation results MUST be able to process *requestLatestSimulationResult*. + +The *requestLatestSimulationResult* data MUST be sent from the consumer of simulation results to the provider of simulation results using an HTTP GET request. The endpoint of the API MUST handle the BPNS of the requesting OSim partner, the requestId and MUST have the simulationRunID of the last received simulation result as a path parameter in the URL. In case the simulationRunID is unknown, "0" is to be used as default. + +Parameters: + +- bpns: is mandatory and MUST to be filled with the BPNS ID of the requestor. +- requestId (UUIDv4): is mandatory and MUST be filled with a newly created unique ID. The value of this parameter MUST be returned by the receiver of the request as an additional URL parameter. It enables the data consumer to correlate the simulation result with the previously sent request and to validate if the received simulation result has been sent by the correct data producer. +- simulationRunId (UUIDv4): is mandatory and MUST be filled by requestor with the ID of the last received simulation result. Otherwise , "0" MUST be sent. + +##### 4.2.2.3 UUID generation and handling + +The UUIDv4 MUST be generated according to RFC 4122. + +##### 4.2.2.4 EDC Data Asset Structure + +The HTTP GET endpoint introduced in chapter [4.2.2.1 API Endpoints & resources](#4221-api-endpoints--resources) MUST NOT be called from a supply chain partner directly. Rather, it MUST be called via an EDC communication. Therefore, the endpoint MUST be offered as an EDC Data Asset. + +- The asset definition MUST have a property “@id”. This property MUST be used to identify the asset when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects the contractual relationship between OSim partners, only one asset with the aforementioned property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen freely but must be unique. +- The asset definition SHOULD contain a property “description” as a sub property of "properties" with a "value" for a human readable description of the asset when providing the contract offer catalog for the consumer and make it easier and readable for a human what kind of data this asset contains. +- The asset definition MUST have a property “dataAddress”."baseUrl" with a value containing the URL of the endpoint where the function **“requestlatestsimulationresult”** is implemented. +- Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the possibility to use the EDC as a reverse proxy by adding parameters to the URL. + +The API version described in this standard document MUST be published in the property `` as version 2.0 in the asset. The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +Each supplier MUST ensure that only their customers have access to the asset by using access and usage policies and respective contract definitions. + +An example EDC Data Asset definition with a corresponding access / usage policy and contract definition are shown below. Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +**Asset definition** + +```json +{ + "@context": { + "edc": "", + "cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)", + "cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)", + "dct": "" + }, + "@id": "osim-request-simulation-result-01", + "properties": { + "description": "Request Simulation Result Asset", + "privateProperties": { + }, + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{OSIM\_REQUEST\_SIMULATION\_RESULT\_ENDPOINT}}", + "method": "GET", + "proxyPath": "true", + "contentType": "application/json" + } +} +``` + +**Access and Usage Policy definition** + +```json +{ + "@context": { + "odrl": "" + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "osim-request-simulation-result-01-policy", + "policy": { + "@type": "Policy", + "odrl:permission" : [{ + "odrl:action" : "USE", + "odrl:constraint" : { + "@type": "LogicalConstraint", + "odrl:or" : [{ + "@type" : "Constraint", + "odrl:leftOperand" : "BusinessPartnerNumber", + "odrl:operator" : { + "@id": "odrl:eq" + }, + "odrl:rightOperand" : "{{POLICY_BPN}}" + }] + } + }] + } +} +``` + +**Contract definition** + +```json +{ + "@context": {}, + "@id": "osim-request-simulation-result-01-contract", + "@type": "ContractDefinition", + "accessPolicyId": "osim-request-simulation-result-01-policy", + "contractPolicyId": "osim-request-simulation-result-01-policy", + "assetsSelector" : { + "@type" : "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "osim-request-simulation-result-01" + } +} +``` + +##### 4.2.2.5 Error Handling + +Every API endpoint defined in chapter [4.2.2.1 API Endpoints & resources](#4221-api-endpoints--resources) MUST respond to incoming requests with HTTP status codes as described in [RFC9110]. All of the following HTTP status codes, except for code 200, MUST be interpreted as failures. Therefore, it may be sufficient for a business application to simply check if the status code is 200 or not. If not, the request failed. + +| HTTP Status Code | HTTP Status Message | Description | +| ---------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | The request has succeeded. The requestLatestSimulationResult has been successfully processed in the backend system. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. | +| 402 | Unknown BPNS | The BPNS which is given as parameter is not registered in the data provider database as a direct partner. | +| 403 | Forbidden | The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. | +| 404 | No simulation results are released | Data provider doesn’t have any **released** simulation results | +| 405 | Method not allowed | The method used to request the data was not POST | +| 406 | No newer simulation available | The simulationRunId which is given as parameter is identical to the currently released simulation run in the data provider database | +| 407 | No shipments planned | No shipments are currently planned for the requestor | +| 500 | Internal Server Error | The server has encountered a situation it does not know how to handle. | +| 503 | Service Unavailable | The server is not ready to handle the request. | + +If one *requestLatestSimulationResult* aspect is transmitted in one HTTP request, the return codes MUST be used as stated in the table above. Applications MAY choose to process valid entries from a list which also contains invalid entries. If *requestLatestSimulationResult* can be processed successfully, the status code 200 MUST be used. + +Further status codes may be included in a later revision of this standard. The ability to send and receive one status code per sent or received list item might be included in a later revision of this standard. + +##### 4.2.2.6 Validating Parameter + +The following tables are supposed to answer questions regarding what business logic MUST be executed when receiving a *requestLatestSimulationResult* which has been formed in a specific way. + +| Number | | 1 | +| -------------- | -------------- | ------------------------------------------------------------------------------ | +| **Properties** | BPNS | Given BPNS is not registered in the data provider database as a direct partner | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 402 - Unknown BPNS | + +### 4.3 "RECEIVE LATEST SIMULATION RESULT" API + +> *This section is normative* + +The *receiveLatestSimulationResult* contains the transfer of the latest simulation result which is sent from lower level partner to a partner on the next higher level. All participants participating in Catena-X OSIM in the role of a provider of simulation results MUST be able to execute the *receiveLatestSimulationResult* API. All participants participating in Catena-X OSIM in the role of a consumer of simulation results MUST be able to receive and process the *receiveLatestSimulationResult* API. + +#### 4.3.1 PRECONDITIONS AND DEPENDENCIES + +The *receiveLatestSimulationResult* API MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the Catena-X standard [CX-0018](#211-list-of-standalone-standards). + +#### 4.3.2 API SPECIFICATION + +##### 4.3.2.1 API Endpoints & resources + +To support the exchange of *receiveLatestSimulationResult* data, a business application MUST define a single endpoint supporting the HTTP POST request method as described in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html). The structure of the endpoint MAY be freely chosen. The address of the endpoint MUST be provided as part of the EDC Data Asset defined in chapter [4.3.2.4 EDC Data Asset Structure](#4324-edc-data-asset-structure). + +##### 4.3.2.2 Data Exchange + +The *receiveLatestSimulationResult* endpoint MUST be implemented by all participants who participate in the Catena-X OSIM network. Consumer of simulation results MUST be able to process *receiveLatestSimulationResult*. The endpoint MUST implement a parameter requestId transmitted by the URL which is used to correlate the sent simulation result to the previously sent request as well as to validate if the sent simulation result is being returned from the receiver of the request. The parameter requestId MUST contain the value of the requestId which has been sent to requestLatestSimulationResult. As the asset definition contains the setting proxyPath set to TRUE the given parameter sent to the data plane of the EDC will be forwarded to the endpoint implementing *receiveLatestSimulationResult*. + +The payload of *receiveLatestSimulationResult* corresponds the data model *MaterialFlowSimulationResult* specified in chapter [3.1 ASPECT MODEL "MaterialFlowSimulationResult"](#31-aspect-model-materialflowsimulationresult). The usage of the attributes in the data model MUST follow the attribute descriptions in the definitions in CX-OSIM-SEMANTICMODEL. While some attributes are technically a string, not any string is valid. For example, “owner” or “recipient” MUST be formatted as a BPNS. + +Only one simulation result is transmitted. + +##### 4.3.2.3 UUID generation and handling + +The UUIDv4 MUST be generated according to RFC 4122. + +##### 4.3.2.4 EDC Data Asset Structure + +The HTTP POST endpoint introduced in chapter [4.3.2.1 API Endpoints & resources](#4321-api-endpoints--resources) MUST NOT be called from a supply chain partner directly. Rather, it MUST be called via an EDC communication. Therefore, the endpoint MUST be offered as an EDC Data Asset. + +- The asset definition MUST have a property “@id”. This property MUST be used to identify the asset when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects the contractual relationship between OSim partners, only one asset with the aforementioned property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen freely but must be unique. +- The asset definition SHOULD contain a property “description” as a sub property of "properties" with a "value" for a human readable description of the asset when providing the contract offer catalog for the consumer and make it easier and readable for a human what kind of data this asset contains. +- The asset definition MUST have a property “dataAddress”."baseUrl" with a value containing the URL of the endpoint where the function **“receivelatestsimulationresult”** is implemented. +- Additionally the dataAddress property MUST contain the following three properties with a value set to TRUE to enable the possibility to use the EDC as a reverse proxy by adding parameters to the URL (proxyPath), allowing POST requests (proxyMethod) and uploading a payload (proxyBody). + - proxyPath + - proxyBody + - proxyMethod + +The API version described in this standard document MUST be published in the property `` as version 2.0 in the asset. The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +Each supplier MUST ensure that only their customers have access to the asset by using access and usage policies and respective contract definitions. + +An example EDC Data Asset definition with a corresponding access / usage policy and contract definition are shown below. Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +**Asset definition** + +```json +{ + "@context": { + "edc": "", + "cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)", + "cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)", + "dct": "" + }, +"@id": "osim-receive-simulation-result-01", +"properties": { + "description": "Receive Simulation Result Asset", + "privateProperties": { + }, + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "proxyPath": "true", + "type": "HttpData", + "proxyMethod": "true", + "baseUrl": "{{OSIM\_RECEIVE\_SIMULATION\_RESULT\_ENDPOINT}}", + "proxyBody": "true", + "contentType": "application/json" + } +} + + +**Access and Usage Policy definition** + +{ + "@context": { + "odrl": "" + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "osim-receive-simulation-result-01-policy", + "policy": { + "@type": "Policy", + "odrl:permission" : [{ + "odrl:action" : "USE", + "odrl:constraint" : { + "@type": "LogicalConstraint", + "odrl:or" : [{ + "@type" : "Constraint", + "odrl:leftOperand" : "BusinessPartnerNumber", + "odrl:operator" : { + "@id": "odrl:eq" + }, + "odrl:rightOperand" : "{{POLICY_BPN}}" + }] + } + }] + } +} +``` + +**Contract definition** + +``` +{ + "@context": {}, + "@id": "osim-receive-simulation-result-01-contract", + "@type": "ContractDefinition", + "accessPolicyId": "osim-receive-simulation-result-01-policy", + "contractPolicyId": "osim-receive-simulation-result-01-policy", + "assetsSelector" : { + "@type" : "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "osim-receive-simulation-result-01" + } +} +``` + +##### 4.3.2.5 Error Handling + +Every API endpoint defined in chapter [4.3.2.1 API Endpoints & resources](#4321-api-endpoints--resources) MUST respond to incoming requests with HTTP status codes as described in \[RFC9110\]. All of the following HTTP status codes, except for codes 200 and 201, MUST be interpreted as failures. Therefore, it may be sufficient for a business application to simply check if the status code is 200 or 201 or not. If not, the request failed. + +| HTTP Status Code | HTTP Status Message | Description | +| ---------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | The POST has succeeded. The receiveLatestSimulationResult has been successfully processed in the backend system. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. | +| 402 | Payload is empty | The payload of the API call is empty. | +| 403 | Forbidden | The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. | +| 404 | Payload structure unknown | The payload structure is unknown or correspond not to the defined semantic model | +| 405 | Method not allowed | The method used to request the data was not POST. | +| 406 | Payload content invalid | The content of the payload is invalid. E.g. “owner unknown” | +| 500 | Internal Server Error | The server has encountered a situation it does not know how to handle. | +| 503 | Service Unavailable | The server is not ready to handle the request. | + +If one receiveLatestSimulationResult aspect is transmitted in one HTTP request, the return codes MUST be used as stated in the table above. Applications MAY choose to process valid entries from a list which also contains invalid entries. If receiveLatestSimulationResult can be processed successfully, the status code 200 MUST be used. + +Further status codes may be included in a later revision of this standard. The ability to send and receive one status code per sent or received list item might be included in a later revision of this standard. + +##### 4.3.2.6 Validating Payload + +The following tables are supposed to answer questions regarding what business logic MUST be executed when receiving a receiveLatestSimulationResult which has been formed in a specific way. + +| Number | | 1 | +| ------------------- | -------------------- | ---------------------------- | +| **Payload** | | MaterialflowSimulationResult | +| **Meta properties** | Any property | *Invalid value* | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 402 Payload is empty | + +| Number | | 2 | +| ------------------- | -------------------- | ----------------------------- | +| **Payload** | | MaterialflowSimulationResult | +| **Meta properties** | Any property | *Invalid value* | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 404 Payload structure unknown | + +| Number | | 3 | +| ------------------- | -------------------- | ---------------------------- | +| **Payload** | | MaterialflowSimulationResult | +| **Meta properties** | Any property | *Invalid value* | +| | All other properties | *Any value* | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 406 Payload content invalid | + +### 4.4 "REQUEST SCENARIO FEEDBACK" API + +> *This section is normative* + +The *requestScenarioFeedback* is a request from a OSim partner for feedback on the possible fulfillment of the described scenario. All participants participating in Catena-X OSim MUST be able to execute the *requestScenarioFeedback API*. All participants participating in Catena-X OSim MUST be able to receive and process the *requestScenarioFeedback API*. + +#### 4.4.1 PRECONDITIONS AND DEPENDENCIES + +The *requestScenarioFeedback* API MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the Catena-X standard [CX-0018](#211-list-of-standalone-standards). + +#### 4.4.2 API SPECIFICATION + +##### 4.4.2.1 API Endpoints & resources + +To support the exchange of requestScenarioFeedback data, a business application MUST define a single endpoint supporting the HTTP POST request method as described in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html). The structure of the endpoint MAY be freely chosen. The address of the endpoint MUST be provided as part of the EDC Data Asset defined in chapter [4.4.2.4 EDC Data Asset Structure](#4424-edc-data-asset-structure). + +##### 4.4.2.2 Data Exchange + +The requestScenarioFeedback endpoint MUST be implemented by all participants who participate in the Catena-X OSIM network and want to use scenario functionality. Provider of scenario feedback MUST be able to process requestScenarioFeedback. + +The requestScenarioFeedback data MUST be sent from the requestor of a feedback to the provider of a scenario feedback using an HTTP POST request. + +The endpoint of the API MUST handle the BPNS of the requesting OSim partner transmitted by the URL. As the asset definition contains the setting proxyPath set to TRUE the given parameter sent to the data plane of the EDC will be forwarded to the endpoint implementing requestScenarioFeedback. + +The payload of requestScenarioFeedback corresponds the data model *MaterialflowScenarioRequest* specified in chapter [3.2 ASPECT MODEL "MaterialFlowScenarioRequest"](#32-aspect-model-materialflowscenariorequest). The usage of the attributes in the data model MUST follow the attribute descriptions in the definitions in the semantic model. While some attributes are technically a string, not any string is valid. For example, “owner” or “recipient” MUST be formatted as a BPNS. + +##### 4.4.2.3 UUID generation and handling + +The UUIDv4 MUST be generated according to RFC 4122. + +##### 4.4.2.4 EDC Data Asset Structure + +The HTTP POST endpoint introduced in chapter [4.4.2.1 API Endpoints & resources](#4421-api-endpoints--resources) MUST NOT be called from a supply chain partner directly. Rather, it MUST be called via an EDC communication. Therefore, the endpoint MUST be offered as an EDC Data Asset. + +- The asset definition MUST have a property “@id”. This property MUST be used to identify the asset when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects the contractual relationship between OSim partners, only one asset with the aforementioned property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen freely but must be unique. +- The asset definition SHOULD contain a property “description” as a sub property of "properties" with a "value" for a human readable description of the asset when providing the contract offer catalog for the consumer and make it easier and readable for a human what kind of data this asset contains. +- The asset definition MUST have a property “dataAddress”."baseUrl" with a value containing the URL of the endpoint where the function **“requestscenariofeedback”** is implemented. +- Additionally the dataAddress property MUST contain the following three properties with a value set to TRUE to enable the possibility to use the EDC as a reverse proxy by adding parameters to the URL (proxyPath), allowing POST requests (proxyMethod) and uploading a payload (proxyBody). + - proxyPath + - proxyBody + - proxyMethod + +The API version described in this standard document MUST be published in the property `` as version 2.0 in the asset. The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +Each supplier MUST ensure that only their customers have access to the asset by using access and usage policies and respective contract definitions. + +An example EDC Data Asset definition with a corresponding access / usage policy and contract definition are shown below. Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +**Asset definition** + +```json +{ + "@context": { + "edc": "", + "cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)", + "cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)", + "dct": "" + }, + "@id": "osim-request-scenario-feedback-01", + "properties": { + "description": "Request Scenario Feedback Asset", + "privateProperties": { + }, + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{OSIM_REQUEST_SCENARIO_FEEDBACK_ENDPOINT}}", + "proxyBody": "true", + "proxyPath": "true", + "proxyMethod": "true", + "contentType": "application/json" + } +} + +**Access and Usage Policy definition** + +{ + "@context": { + "odrl": "" + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "osim-request-scenario-feedback-01-policy", + "policy": { + "@type": "Policy", + "odrl:permission" : [{ + "odrl:action" : "USE", + "odrl:constraint" : { + "@type": "LogicalConstraint", + "odrl:or" : [{ + "@type" : "Constraint", + "odrl:leftOperand" : "BusinessPartnerNumber", + "odrl:operator" : { + "@id": "odrl:eq" + }, + "odrl:rightOperand" : "{{POLICY_BPN}}" + }] + } + }] + } +} +``` + +**Contract definition** + +``` +{ + "@context": {}, + "@id": "osim-request-scenario-feedback-01-contract", + "@type": "ContractDefinition", + "accessPolicyId": "osim-request-scenario-feedback-01-policy", + "contractPolicyId": "osim-request-scenario-feedback-01-policy", + "assetsSelector" : { + "@type" : "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "osim-request-scenario-feedback-01" + } +} +``` + +##### 4.4.2.5 Error Handling + +Every API endpoint defined in chapter [4.4.2.1 API Endpoints & resources](#4421-api-endpoints--resources) MUST respond to incoming requests with HTTP status codes as described in \[RFC9110\]. All of the following HTTP status codes, except for code 200, MUST be interpreted as failures. Therefore, it may be sufficient for a business application to simply check if the status code is 200 or not. If not, the request failed. + +| HTTP Status Code | HTTP Status Message | Description | +| ---------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | The request has succeeded. The *requestScenarioFeedback* has been successfully processed in the backend system. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. | +| 402 | Unknown BPNS | The BPNS which is given as parameter is not registered in the data provider database as a direct partner. | +| 403 | Forbidden | The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. | +| 405 | Method not allowed | The method used to request the data was not POST | +| 500 | Internal Server Error | The server has encountered a situation it does not know how to handle. | +| 503 | Service Unavailable | The server is not ready to handle the request. | + +If one *requestScenarioFeedback* aspect is transmitted in one HTTP request, the return codes MUST be used as stated in the table above. Applications MAY choose to process valid entries from a list which also contains invalid entries. If *requestScenarioFeedback* can be processed successfully, the status code 200 MUST be used. + +Further status codes may be included in a later revision of this standard. The ability to send and receive one status code per sent or received list item might be included in a later revision of this standard. + +##### 4.4.2.6 Validating Parameter + +The following tables are supposed to answer questions regarding what business logic MUST be executed when receiving a *requestScenarioFeedback* which has been formed in a specific way. + +| Number | | 1 | +| -------------- | -------------- | ------------------------------------------------------------------------------ | +| **Properties** | BPNS | Given BPNS is not registered in the data provider database as a direct partner | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 402 - Unknown BPNS | + +### 4.5 "RECEIVE SCENARIO FEEDBACK" API + +> *This section is normative* + +The receiveScenarioFeedback enables the requestor to transmit the result of his scenario-based evaluation to the requestor. All participants participating in Catena-X OSim MUST be able to execute the receiveScenarioFeedback API. All participants participating in Catena-X OSim MUST be able to receive and process the receiveScenarioFeedback API. + +#### 4.5.1 PRECONDITIONS AND DEPENDENCIES + +The ***receiveScenarioFeedback*** API MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the Catena-X standard [CX-0018](#211-list-of-standalone-standards). + +#### 4.5.2 API SPECIFICATION + +##### 4.5.2.1 API Endpoints & resources + +To support the exchange of *receiveScenarioFeedback* data, a business application MUST define a single endpoint supporting the HTTP GET request method as described in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html). The structure of the endpoint MAY be freely chosen. The address of the endpoint MUST be provided as part of the EDC Data Asset defined in chapter [4.5.2.4 EDC Data Asset Structure](#4524-edc-data-asset-structure). + +##### 4.5.2.2 Data Exchange + +The receiveScenarioFeedback endpoint MUST be implemented by all participants who participate in the Catena-X OSIM network. Receiver of scenario feedback MUST be able to process *receiveScenarioFeedback API*. + +The *receiveScenarioFeedback* data MUST be sent from the provider of scenario feedback to the receiver of scenario feedback using an HTTP GET call. The endpoint of the API MUST handle the BPNS of the requesting OSim partner, the scenario ID and the feedback value as a path parameter in the URL. + +Parameters: + +- bpns: is mandatory and MUST to be filled with the BPNS ID of the feedback provider. +- scenarioId (UUIDv4): is mandatory and MUST be filled with a unique ID. The value of this parameter MUST be returned by the feedback provider as an additional URL parameter. +- feedback (ENUM): is mandatory and MUST be filled by feedback provider with the enumeration value of the scenario feedback. The following values are allowed: + +| State | Description | +| ------------- | ------------------------------------------- | +| Realizable | The partner has confirmed the feasibility | +| NotRealizable | The partner has rejected the implementation | + +##### 4.5.2.3 UUID generation and handling + +The UUIDv4 MUST be generated according to RFC 4122. + +##### 4.5.2.4 EDC Data Asset Structure + +The HTTP GET endpoint introduced in chapter [4.5.2.1 API Endpoints & resources](#4521-api-endpoints--resources) MUST NOT be called from a supply chain partner directly. Rather, it MUST be called via an EDC communication. Therefore, the endpoint MUST be offered as an EDC Data Asset. + +- The asset definition MUST have a property “@id”. This property MUST be used to identify the asset when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects the contractual relationship between OSim partners, only one asset with the aforementioned property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen freely but must be unique. +- The asset definition SHOULD contain a property “description” as a sub property of "properties" with a "value" for a human readable description of the asset when providing the contract offer catalog for the consumer and make it easier and readable for a human what kind of data this asset contains. +- The asset definition MUST have a property “dataAddress”."baseUrl" with a value containing the URL of the endpoint where the function **“receivescenariofeedback”** is implemented. +- Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the possibility to use the EDC as a reverse proxy by adding parameters to the URL. + +The API version described in this standard document MUST be published in the property `` as version 2.0 in the asset. The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +Each supplier MUST ensure that only their customers have access to the asset by using access and usage policies and respective contract definitions. + +An example EDC Data Asset definition with a corresponding access / usage policy and contract definition are shown below. Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +**Asset definition** + +``` +{ + "@context": { + "edc": "", + "cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)", + "cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)", + "dct": "" + }, + "@id": "osim-receive-scenario-feedback-01", + "properties": { + "description": "Receive Scenario Feedback Asset", + "privateProperties": { + }, + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "proxyPath": "true", + "type": "HttpData", + "baseUrl": "{{OSIM_RECEIVE_SCENARIO_FEEDBACK_ENDPOINT}}", + "method": "GET", + "contentType": "application/json" + } +} +``` + +**Access and Usage Policy definition** + +``` +{ + "@context": { + "odrl": "" + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "osim-receive-scenario-feedback-01-policy", + "policy": { + "@type": "Policy", + "odrl:permission" : [{ + "odrl:action" : "USE", + "odrl:constraint" : { + "@type": "LogicalConstraint", + "odrl:or" : [{ + "@type" : "Constraint", + "odrl:leftOperand" : "BusinessPartnerNumber", + "odrl:operator" : { + "@id": "odrl:eq" + }, + "odrl:rightOperand" : "{{POLICY_BPN}}" + }] + } + }] + } +} +``` + +**Contract definition** + +```json +{ + "@context": {}, + "@id": "osim-receive-scenario-feedback-01-contract", + "@type": "ContractDefinition", + "accessPolicyId": "osim-receive-scenario-feedback-01-policy", + "contractPolicyId": "osim-receive-scenario-feedback-01-policy", + "assetsSelector" : { + "@type" : "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "osim-receive-scenario-feedback-01" + } +} +``` + +##### 4.5.2.5 Error Handling + +Every API endpoint defined in chapter [4.5.2.1 API Endpoints & resources](#4521-api-endpoints--resources) MUST respond to incoming requests with HTTP status codes as described in \[RFC9110\]. All of the following HTTP status codes, except for code 200, MUST be interpreted as failures. Therefore, it may be sufficient for a business application to simply check if the status code is 200 or not. If not, the request failed. + +| **HTTP Status Code** | **HTTP Status Message** | **Description** | +| -------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | The POST has succeeded. The *receiveScenarioFeedback* has been successfully processed in the backend system. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Authorized | Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. | +| 402 | Unknown BPNS | The BPNS which is given as parameter is not registered in the data provider database as a direct partner. | +| 403 | Forbidden | The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. | +| 405 | Method not allowed | The method used to request the data was not POST. | +| 406 | Unknown Scenario | The scenarioID which is given as parameter is not registered. | +| 407 | Unknown State | The feedbackState value is unknown. | +| 500 | Internal Server Error | The server has encountered a situation it does not know how to handle. | +| 503 | Service Unavailable | The server is not ready to handle the request. | + +If one *receiveScenarioFeedback* aspect is transmitted in one HTTP request, the return codes MUST be used as stated in the table above. Applications MAY choose to process valid entries from a list which also contains invalid entries. If*receiveScenarioFeedback* can be processed successfully, the status code 200 MUST be used. + +Further status codes may be included in a later revision of this standard. The ability to send and receive one status code per sent or received list item might be included in a later revision of this standard. + +##### 4.5.2.6 Validating Parameter + +The following tables are supposed to answer questions regarding what business logic MUST be executed when receiving a *receiveScenarioFeedback* which has been formed in a specific way. + +| Number | | 1 | +| -------------- | -------------- | ------------------------------------------------------------------------------ | +| **Properties** | BPNS | Given BPNS is not registered in the data provider database as a direct partner | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 402 - Unknown BPNS | + +| Number | | 2 | +| -------------- | -------------- | ---------------------------- | +| **Properties** | scenarioId | Given Scenario Id is unknown | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 406 - Unknown Scenario | + +| Number | | 3 | +| -------------- | -------------- | ------------------------------ | +| **Properties** | feedback | Given feedback enum is unknown | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 407 - Unknown state | + +### 4.6 "PUSH SCENARIO STATE" API + +> *This section is normative* + +The *pushScenarioState* enables distribution of a new scenario status and thus a notification of the procedure with the planned scenario. All participants participating in Catena-X OSim MUST be able to execute the *pushScenarioState API*. All participants participating in Catena-X OSim MUST be able to receive and process the *pushScenarioState API*. + +#### 4.6.1 PRECONDITIONS AND DEPENDENCIES + +The *pushScenarioState* API MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the Catena-X standard [CX-0018](#211-list-of-standalone-standards). + +#### 4.6.2 API SPECIFICATION + +##### 4.6.2.1 API Endpoints & resources + +To support the exchange of *pushScenarioState* data, a business application MUST define a single endpoint supporting the HTTP GET request method as described in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html). The structure of the endpoint MAY be freely chosen. The address of the endpoint MUST be provided as part of the EDC Data Asset defined in chapter [4.6.2.4 EDC Data Asset Structure](#4624-edc-data-asset-structure). + +##### 4.6.2.2 Data Exchange + +The *pushScenarioState* endpoint MUST be implemented by all participants who participate in the Catena-X OSIM network. Receiver of scenario state MUST be able to process *pushScenarioState API*. + +The *pushScenarioState* data MUST be sent from the provider of scenario state to the receiver of scenario state using an HTTP GET call. The endpoint of the API MUST handle the BPNS of the requesting OSim partner, the scenario ID and the state value as a path parameter in the URL. + +Parameters: + +- bpns: is mandatory and MUST to be filled with the BPNS ID of the feedback provider. +- scenarioId (UUIDv4): is mandatory and MUST be filled with a unique ID. The value of this parameter MUST be returned by the feedback provider as an additional URL parameter. +- state (ENUM): is mandatory and MUST be filled by feedback provider with the enumeration value of the scenario feedback. The following values are allowed: + +| State | Description | +| ------------- | ---------------------------------------------------- | +| InRealization | Organisational measures initiated | +| Processed | Organisational measures implemented | +| Canceled | All affected partners informed about the termination | + +The payload of *pushScenarioState* is a free text comment, which MAY be sent additionally to the new state of a scenario. No structure is needed for the payload. + +##### 4.6.2.3 UUID generation and handling + +The UUIDv4 MUST be generated according to RFC 4122. + +##### 4.6.2.4 EDC Data Asset Structure + +The HTTP GET endpoint introduced in chapter [4.6.2.1 API Endpoints & resources](#4621-api-endpoints--resources) MUST NOT be called from a supply chain partner directly. Rather, it MUST be called via an EDC communication. Therefore, the endpoint MUST be offered as an EDC Data Asset. + +- The asset definition MUST have a property “@id”. This property MUST be used to identify the asset when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects the contractual relationship between OSim partners, only one asset with the aforementioned property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen freely but must be unique. +- The asset definition SHOULD contain a property “description” as a sub property of "properties" with a "value" for a human readable description of the asset when providing the contract offer catalog for the consumer and make it easier and readable for a human what kind of data this asset contains. +- The asset definition MUST have a property “dataAddress”."baseUrl" with a value containing the URL of the endpoint where the function **“pushscenariostate”** is implemented. +- Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the possibility to use the EDC as a reverse proxy by adding parameters to the URL. + +The API version described in this standard document MUST be published in the property `` as version 2.0 in the asset. The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +Each supplier MUST ensure that only their customers have access to the asset by using access and usage policies and respective contract definitions. + +An example EDC Data Asset definition with a corresponding access / usage policy and contract definition are shown below. Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +**Asset definition** + +```json +{ + "@context": { + "edc": "", + "cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)", + "cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)", + "dct": "" + }, + "@id": "osim-push-scenario-state-01", + "properties": { + "description": "Push Scenario State Asset", + "privateProperties": { + }, + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "proxyPath": "true", + "type": "HttpData", + "baseUrl": "{{OSIM_PUSH_SCENARIO_STATE_ENDPOINT}}", + "method": "GET", + "contentType": "application/json" + } +} + + +``` + +**Access and Usage Policy definition** + +```json +{ + "@context": { + "odrl": "" + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "osim-push-scenario-state-01-policy", + "policy": { + "@type": "Policy", + "odrl:permission" : [{ + "odrl:action" : "USE", + "odrl:constraint" : { + "@type": "LogicalConstraint", + "odrl:or" : [{ + "@type" : "Constraint", + "odrl:leftOperand" : "BusinessPartnerNumber", + "odrl:operator" : { + "@id": "odrl:eq" + }, + "odrl:rightOperand" : "{{POLICY_BPN}}" + }] + } + }] + } +} + + + +``` + +**Contract definition** + +``` +{ + "@context": {}, + "@id": "osim-push-scenario-state-01-contract", + "@type": "ContractDefinition", + "accessPolicyId": "osim-push-scenario-state-01-policy", + "contractPolicyId": "osim-push-scenario-state-01-policy", + "assetsSelector" : { + "@type" : "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "osim-push-scenario-state-01" + } +} +``` + +##### 4.6.2.5 Error Handling + +Every API endpoint defined in chapter [4.6.2.1 API Endpoints & resources](#4621-api-endpoints--resources) MUST respond to incoming requests with HTTP status codes as described in \[RFC9110\]. All of the following HTTP status codes, except for code 200, MUST be interpreted as failures. Therefore, it may be sufficient for a business application to simply check if the status code is 200 or not. If not, the request failed. + +| **HTTP Status Code** | **HTTP Status Message** | **Description** | +| -------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | The POST has succeeded. The *pushScenarioState* has been successfully processed in the backend system. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Authorized | Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. | +| 402 | Unknown BPNS | The BPNS which is given as parameter is not registered in the data provider database as a direct partner. | +| 403 | Forbidden | The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. | +| 405 | Method not allowed | The method used to request the data was not POST. | +| 406 | Unknown Scenario | The scenarioID which is given as parameter is not registered. | +| 407 | Unknown State | The scenarioState value is unknown. | +| 500 | Internal Server Error | The server has encountered a situation it does not know how to handle. | +| 503 | Service Unavailable | The server is not ready to handle the request. | + +If one *pushScenarioState* aspect is transmitted in one HTTP request, the return codes MUST be used as stated in the table above. Applications MAY choose to process valid entries from a list which also contains invalid entries. If*pushScenarioState* can be processed successfully, the status code 200 MUST be used. + +Further status codes may be included in a later revision of this standard. The ability to send and receive one status code per sent or received list item might be included in a later revision of this standard. + +##### 4.6.2.6 Validating Parameter + +The following tables are supposed to answer questions regarding what business logic MUST be executed when receiving a *pushScenarioState* which has been formed in a specific way. + +| Number | | 1 | +| -------------- | -------------- | ------------------------------------------------------------------------------ | +| **Properties** | BPNS | Given BPNS is not registered in the data provider database as a direct partner | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 402 - Unknown BPNS | + +| Number | | 2 | +| -------------- | -------------- | ---------------------------- | +| **Properties** | scenarioId | Given Scenario Id is unknown | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 406 - Unknown Scenario | + +| Number | | 3 | +| -------------- | -------------- | --------------------------- | +| **Properties** | state | Given state enum is unknown | +| **Actions** | Business Logic | Ignore received values | +| | Return Code | 407 - Unknown State | + +## 5 PROCESSES + +> *This section is* *normative* + +### 5.1 "Online Control and Simulation" PROCESS + +#### 5.1.1 ACTORS AND ROLES + +Any **application provider** that develops OSim solutions has to grant the fulfillment of these requirements: + +- The solution MUST be designed to require a contractual agreement in compliance with antitrust requirements in the usage environment (e.g. data contracts as a prerequisite for carrying out a data exchange). For reference see Chapter 8 and follow EDC (CX-0001) guidelines. +- The solution MUST be designed to limit visibility and/or access to concrete data content as much as necessary (e.g. data offer does not yet allow data access). +- The solution MUST be designed to require the implementation of notice and/or acknowledgement concepts to raise awareness of antitrust issues during use (e.g. helpdesk or pop-up info). +- The solution MUST be designed to ensure traceability/reconstructability of processes through appropriate documentation and at the same time data sovereignty over concrete data content (e.g. through access, deletion or destination rights). + +Any **customer, supplier and logistician** (in following called with “all parties”) **in the OSim process** (i.e. data provider and/or data consumer) MUST fulfil following requirements: + +- All parties are in a contractual relationship with parties in the next higher and lower tier levels that they want to exchange data and MUST agree to share data related to OSim. +- All parties MUST manage the access authorization to a OSim solution and to its related data. +- All parties in the role of data provider MUST ensure, the authorized data consumers will get data directly relevant to him only. +- For **basic flow** + - All parties in the role of data provider MUST be able to generate (e.g. with simulation tool), and release simulation results. + - Each data provider MUST have maximum one released simulation result at time + - Data providers released simulation results MUST be made accessible by authorized data consumers (e.g. logisticians or customers) of an upper level in the supply chain. + - All parties in the role of data consumer MUST be able to request and receive simulation results from the next lower level in the supply chain. + - The parties SHOULD use received simulation results from lower partners for the own material flow simulation. + - It is RECOMMENDED to share simulation results of a time window of 2 to 4 weeks, as the aim of OSim is to optimize the short-term simulation. +- For **scenario flow** + - All parties in the role of data provider MUST be able to create a scenario and to generate own simulation results (e.g. with simulation tools), and request a feedback by affected partners. + - All parties in the role of data consumer MUST be able to receive scenario feedback requests, generate own simulation results (e.g. with simulation tools), and send feedbacks to the requestor. +- It is RECOMMENDED that each partner uses a professional simulation tool to generate the simulation results, so that the overall data quality can be increased. +- Alternatively, the OSim partner MAY build simulation results out of detailed planning data (e.g. generate them manually), instead of using simulation tools. + +#### 5.1.2 PROCESS REPRESENTATION + +see chapter [1.4.1 Process Examples](#141-process-examples) + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is* *normative* + +- CX-0001 EDC Discovery API Version 1.0.2 +- CX-0003 SAMM Aspect Meta Model Version 1.1.0 or 1.0.2 +- CX-0018 Dataspace Connectivity Version 3.0.0 + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +n.a. + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +n.a. + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0133-OnlineControlandSimulation/assets/MaterialFlowSimulationResult.png b/docs/standards/CX-0133-OnlineControlandSimulation/assets/MaterialFlowSimulationResult.png new file mode 100644 index 000000000..f29add07c Binary files /dev/null and b/docs/standards/CX-0133-OnlineControlandSimulation/assets/MaterialFlowSimulationResult.png differ diff --git a/docs/standards/CX-0133-OnlineControlandSimulation/assets/ScenarioFlow.png b/docs/standards/CX-0133-OnlineControlandSimulation/assets/ScenarioFlow.png new file mode 100644 index 000000000..af3fb96a8 Binary files /dev/null and b/docs/standards/CX-0133-OnlineControlandSimulation/assets/ScenarioFlow.png differ diff --git a/docs/standards/CX-0133-OnlineControlandSimulation/assets/TierLevels.png b/docs/standards/CX-0133-OnlineControlandSimulation/assets/TierLevels.png new file mode 100644 index 000000000..25b441a84 Binary files /dev/null and b/docs/standards/CX-0133-OnlineControlandSimulation/assets/TierLevels.png differ diff --git a/docs/standards/CX-0133-OnlineControlandSimulation/assets/api-interactions.svg b/docs/standards/CX-0133-OnlineControlandSimulation/assets/api-interactions.svg new file mode 100644 index 000000000..9833b9c55 --- /dev/null +++ b/docs/standards/CX-0133-OnlineControlandSimulation/assets/api-interactions.svg @@ -0,0 +1,3 @@ + + +
    OSim Manager
    APP

    Available Information before call : 
    myBPNS = "A"
    BPNS of my partner = "B"
    LastReceivedSimResultID from "B" = "123"


    Steps:
    1. Call requestLatestSimulationResult(
             BPNS of "A",
             ID of the last Simulation Result from "B",
             )










    2. Receive Return Value
    2.1 
    IF retval = NoNewerSimulationAvailable THEN 
    do nothing
    ELSEIF retval <> OK
    Delete/Archive last received simulation result                from "B"
    END IF


    3. Persist the received simulation result 




    4. Return OK/NOK

    OSim Manager...
    requestLatestSimulationResult(
    BPNS of "A",
    ID of the last Simulation Result from "B",
    RequestID generated by "A" for this request-call)

    requestLatestSimulationResult(...
    OSim Manager
    APP

    Available Information receiving the request call : 
    myBPNS = "B"
    BPNS of my partner = "A"
    myLastSimResultID = "789"
    RequestID = GUID generated by "A"

    Steps to provide simResults to "A" :

    2.1. Check, if "A" is my partner in the OSim network configuration 
    IF FALSE Return "UnknownBPNS"

    2.2. Execute Querry :
    SELECT * FROM SimResult WHERE
    Status = "Released"

    2.3. IF NoDataFound
      Return "NoSimulationResultsReleased"

    2.4. Avoid sending the same SimResult twice
    IF selectedSimResultID = inputSimResultID THEN
      Return "NoNewerSimulationAvailable"

    2.5. Filter Shipments of the selcted SimResult to Requestors BPNS
    --> Shipment.DestinationBPNS = "A"

    2.6. IF NoDataFound
      Return "NoShipmentsPlanned"
    ELSE
    - Temporary persist the data Request. The Simulation Result will be sent  with a separate call
    - Return OK

    3 Call receiveLatestSimulationResult (
    RequestID,
    latest released simulation result)

    OSim Manager...
    1
    1
    2
    2
    Return Value:
    {
    UnknownBPNS,
    NoSimulationResultsReleased, 
    NoNewerSimulationAvailable,
    NoShipmentsPlanned,
    OK
     }
    Return Value:...
    3
    3
    receiveLatestSimulationResult(
    RequestID,
    MaterialflowSimulationResult)

    receiveLatestSimulationResult(...
    Return Value:
    {
    OK,
    NOK
     }
    Return Value:...
    4
    4
    Data consumer
    Data consumer
    Data provider
    Data provider     Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0133-OnlineControlandSimulation/assets/example.png b/docs/standards/CX-0133-OnlineControlandSimulation/assets/example.png new file mode 100644 index 000000000..76c458b02 Binary files /dev/null and b/docs/standards/CX-0133-OnlineControlandSimulation/assets/example.png differ diff --git a/docs/standards/CX-0133-OnlineControlandSimulation/assets/image-2023-11-14_11-32-9-1.png b/docs/standards/CX-0133-OnlineControlandSimulation/assets/image-2023-11-14_11-32-9-1.png new file mode 100644 index 000000000..65b88fa47 Binary files /dev/null and b/docs/standards/CX-0133-OnlineControlandSimulation/assets/image-2023-11-14_11-32-9-1.png differ diff --git a/docs/standards/CX-0133-OnlineControlandSimulation/assets/image-2023-8-29_11-10-24.svg b/docs/standards/CX-0133-OnlineControlandSimulation/assets/image-2023-8-29_11-10-24.svg new file mode 100644 index 000000000..1bd1dee4b --- /dev/null +++ b/docs/standards/CX-0133-OnlineControlandSimulation/assets/image-2023-8-29_11-10-24.svg @@ -0,0 +1,3 @@ + + +
    OSim Manager
    APP

    Available Information before call : 
    myBPNS = "A"
    BPNS of my partner = "B"
    Role = I'm the owner"


    Steps:
    1. Call requestScenarioFeedback(
             BPNS of "A",
             ScenarioData,
             )
























    7. Operator takes a decision about scenario implementation

    7.1 IF "I want to implement this scenario THEN 
    - Set Scenario State = "In realization"
    - Call PushScenarioState (State = "In realization")
    - Start scenario implementation in the Planning / 
      Operations management systems 
    ELSE
    - Set Scenario State = "Cancelled"
    - Call PushScenarioState (State = "Cancelled")





    OSim Manager...
    requestScenarioFeedback(
    BPNS of "A",
    ScenarioData)

    requestScenarioFeedback(...
    OSim Manager
    APP

    Available Information receiving the request call : 
    myBPNS = "B"
    BPNS of my partner = "A"
    BPNS of my partner = "C"
    Scenario Data

    Steps:

    2.1. Check, if "A" is my partner in the OSim network configuration 
    IF FALSE Return "UnknownBPNS"



    3.1. Trigger own simulation

    3.2. IF NotAchievable
      Call receiveScenarioFeedback()
      END!
    End 

    3.3 IF Dependency on the next Level (e.g. "C") Then
    Call Request ScenarioFeedback(
    BPNS = "C",
    ScenarioData) 





    6.1. Call receiveScenarioFeedback(ScenarioID, Feedback)










    8.1 Set ScenarioState = received ScenarioState
    8.2 Call PushScenarioState (State = received State)

    OSim Manager...
    1
    1
    2
    2
    Return Value:
    {
    UnknownBPNS,
    OK
     }
    Return Value:...
    6
    6
    receiveScenarioFeedback(
    ScenarioID,
    Feedback)

    receiveScenarioFeedback(...
    Supplier
    Supplier
    Logistician
    Logistician
    OSim Manager
    APP

    Available Information receiving the request call : 
    myBPNS = "C"
    BPNS of my partner = "B"




    Steps:













    4.1. Check, if "A" is my partner in the OSim network configuration 
    IF FALSE Return "UnknownBPNS"




    5.1. Trigger own simulation

    5.2. IF NotAchievable
      Call receiveScenarioFeedback( notAchievable )
    ELSE
      Call receiveScenarioFeedback( Achievable )













    9.1 Set ScenarioState = received ScenarioId


    OSim ManagerAPP...
    Customer
    Customer
    3
    3
    ReceiveScenarioFeedback
    {
    ScenarioID, 
    Feedback =notAchievable,
     }
    ReceiveScenarioFeedback...
    requestScenarioFeedback(
    BPNS of "B",
    ScenarioData)

    requestScenarioFeedback(...
    3
    3
    4
    4
    Return Value:
    {
    UnknownBPNS / OK
     }
    Return Value:...
    5
    5
    receiveScenarioFeedback(
    ScenarioID, 
    Feedback )
    receiveScenarioFeedback(...
    pushScenarioState(
    ScenarioID,
    State)

    pushScenarioState(...
    7
    7
    pushScenarioState(
    ScenarioID,
    State)

    pushScenarioState(...
    8
    8    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0133-OnlineControlandSimulation/assets/image2023-8-21_16-1-19.png b/docs/standards/CX-0133-OnlineControlandSimulation/assets/image2023-8-21_16-1-19.png new file mode 100644 index 000000000..515a91ea8 Binary files /dev/null and b/docs/standards/CX-0133-OnlineControlandSimulation/assets/image2023-8-21_16-1-19.png differ diff --git a/docs/standards/CX-0135-CompanyCertificateManagement/CX-0135-CompanyCertificateManagement.md b/docs/standards/CX-0135-CompanyCertificateManagement/CX-0135-CompanyCertificateManagement.md new file mode 100644 index 000000000..793c48ccf --- /dev/null +++ b/docs/standards/CX-0135-CompanyCertificateManagement/CX-0135-CompanyCertificateManagement.md @@ -0,0 +1,330 @@ +# CX-0135 - BP company certificate management v2.0.0 + +## ABSTRACT + +*This section is non-normative.* + +In the world of business, company certificates are often mandatory for conducting transactions between two companies. However, the process of provisioning, maintaining, and validating these certificates can be a major challenge. For example, if a company has 100 customers, they may need to provide their company certificates in 100 different ways and maintain them at 100 different points. + +To address this issue, a use case has been developed that provides a standardized but generic data model for company certificates. This allows companies to provide and exchange certificates on a defined standard within the scope of the Catena-X dataspace. The second part of this use case focuses on the technological aspect of providing and validating certificates via an interface. + +This standard is relevant for business application providers who wish to establish a solution for managing and validating company certificates, and returning them to customers. It is also important for data providers and consumers who need to exchange or validate certificates through a solution provider. + +## FOR WHOM IS THE STANDARD DESIGNED + +This standard is crucial for business application providers looking to implement a sturdy solution for consuming, providing, and validating company certificates, which can be effortlessly returned to customers. Moreover, data providers and consumers who need a dependable means of exchanging or validating certificates through a solution provider or even the certificate issuer itself will find this standard to be of immense importance. By complying with this standard, businesses can ensure seamless certificate management and validation, thereby enhancing their overall operations. + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +Added a new attribute 'status' to the data model (1.5.11 STATUS) +Added new certificate types (1.5.2 TYPE) + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +*This section is non-normative.* + +This standard is relevant for the following audience: + +- Business Application Provider +- Data Provider and Consumer + +This standard applies to business application providers who wish to establish a solution for managing and validating company certificates, and returning them to customers. It is also important for data providers and consumers who need to exchange or validate certificates through a solution provider. + +The data model for company certificates included in this standard is generic and supports the following certificates: IATF 16949, ISO 14001, ISO 9001, ISO 27001, and VDA6.4. + +Additional certificates may be added in the future. + +You can find the other standards in the standard library of Catena-X: https://catena-x.net/de/standard-library. + +### 1.2 CONTEXT + +*This section is non-normative.* + +The establishment of various industry networks, such as Catena-X, has significantly increased the need for data standards across the entire automotive value chain. To promote industry-wide, international data exchange and facilitate networking between OEMs, suppliers, customers, and industrial partners, it is essential to define and introduce a cross-industry standard for the provisioning, exchanging, maintenance, and validation of company certificates. This standard ensures interoperability and data sovereignty, while also increasing trust in certificates. + +By implementing this standard, companies can streamline the process of managing and exchanging certificates, reducing the burden of maintaining multiple certificates for different customers. Additionally, the standard ensures that certificates are validated and exchanged in a secure and reliable manner, enhancing trust and confidence in the data exchange process. Overall, the introduction of a cross-industry standard for company certificates is a crucial step towards achieving seamless and secure data exchange across the automotive industry. + +### 1.3 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD and SHOULD NOT in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) [[RFC2119](https://www.w3.org/TR/did-core/#bib-rfc2119 "Key words for use in RFCs to Indicate Requirement Levels")] [[RFC8174](https://www.w3.org/TR/did-core/#bib-rfc8174 "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words")] when, and only when, they appear in all capitals, as shown here. + +*This section is non-normative.* + +All participants and their solutions will need to proof, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +### 1.4 EXAMPLES + +A company that has 100 customers, they may need to provide their company certificates in up to 100 different ways and maintain them manually at 100 different points (typically proprietary customer portals). +A company has 100 customers, that provide different certificates, from different countries and they need to validate them. + +### 1.5 TERMINOLOGY + +*This section is non-normative.* + +In this section the different parts of the data model are explained. + +The data model is implemented according to the API specification that is published in the Tractus-X open source repository: +[BPDM certificate management api](https://github.com/eclipse-tractusx/bpdm-certificate-management/tree/main/doc/api)(v1.0.0) + +#### 1.5.1 BPNL BUSINESS PARTNER NUMBER LEGAL ENTITY + +A BPNL represents and uniquely identifies a Legal Entity, which is defined by its legal name (including Legal Form, if registered), legal Address and Tax Number. For further details on BPNLs please see standard 0010 Business Partner Number. + +For this standard and the data model the BPNL is the BPN id of the certified legal entity. + +Attribute: businessPartnerNumber + +#### 1.5.2 TYPE + +Attribute: certitificateType +Attribute: certificateVersion + +Is the type of the certificate the BPN is certified for. This data model is generic and supports the following certificates (additional certificates may be added in the future): + +IATF 16949 (International Automotive Task Force) is a standard that defines the requirements for a quality management system in the automotive industry. + +ISO 14001 is a standard that outlines the requirements for an environmental management system to help organizations minimize their impact on the environment. + +ISO 9001 is a standard that sets out the requirements for a quality management system to help organizations consistently provide products and services that meet customer and regulatory requirements. + +ISO 45001, OHSAS 18001 or national certification are occupational health and safety management system standards that help companies identify and manage workplace hazards to prevent accidents and injuries. + +ISO/IEC 27001 is an information security management system standard that provides a framework for companies to manage and protect their sensitive information. + +ISO 50001 or national certification is an energy management system standard that helps companies improve energy efficiency and reduce costs. + +ISO/IEC 17025 is a laboratory accreditation standard that ensures the accuracy and reliability of testing and calibration results. + +ISO 15504 (SPICE) is a process assessment model that helps companies improve the quality and efficiency of their software development processes. + +ISO 20000 is an IT service management system standard that helps companies deliver high-quality IT services to their customers. + +ISO 22301 is a business continuity management system standard that helps companies prepare for and respond to unexpected disruptions to their operations. + +AEO (Authorized Economic Operator), CTPAT (Customs-Trade Partnership Against Terrorism), Security Declaration is an internationally recognized certificate that confirms a company's compliance with customs regulations and supply chain security standards. CTPAT (Customs-Trade Partnership Against Terrorism) is a voluntary program that promotes supply chain security and trade compliance with U.S. Customs and Border Protection. Security Declaration is a document that outlines a company's security measures and procedures for the transportation of goods. + +VDA6.4 is a standard that defines the requirements for a quality management system in the automotive industry, with a focus on process auditing. + +Note: The spelling of the certificate type may vary slightly on the user interface or within the data model. + +#### 1.5.3 REGISTRATION AND ISSUING + +Attribute: issuer +Attribute: registrationNumber + +Issuer authority is the one who is handing out a certificate - e.g. TUEV Sued. The registration number is the certificate unique identifier at the certifying authority / issuing agency. + +Example: ISO 9001 certificate is issued by TÜV Süd and they are the certifying authority. + +#### 1.5.4 AREA OF APPLICATION + +Attribute: areaOfApplication + +It is the area of applications for the given certification i.e. additional details. + +#### 1.5.5 ENCLOSED SITES + +Attribute: enclosedSites + +This attribute is closely linked to the business partner number (BPN) and indicates additional sites, such as production or engineering sites, that are covered by the certificate. In other words, the certificate is valid not only for the primary BPN, but also for any associated sites. This attribute is particularly useful for companies with multiple locations or business units, as it allows them to manage certificates more efficiently and ensures that all relevant sites are covered by the certificate. + +#### 1.5.6 VALIDITY + +Attribute: validFrom +Attribute: validUntil + +This is the valid from date for certificate, if not defined - its recommended to use the issueing/signing date of the document. Related to the valid from date there is the valid to date for a certificate - 31.12.9999 for no expiration. + +#### 1.5.7 TRUST LEVEL + +Attribute: trustLevel + +Data object defining the trust level of the certicate. + +The certificates are provided in the business context by the company itself - they are showing their certificates to other companies. Not every certificate can be directly validated by the issuing authority. Thats why there are different trust levels defined: none/ low /high / trusted. + +None: no validation check at all, just uploaded / provided by the company +Low: manual validation check done by human after upload +Medium: certificate provided by trusted issuer and manually checked (as low) +High: automated cross check via some database (e.g. TÜV, IATF) +Trusted: directly provided by issuer (e.g. TÜV) + +#### 1.5.8 VALIDATOR + +Attribute: validator + +Validator is the one who can validate certificate information. In the best way it is the authority that is issuing the certificates but there can be other validators. This attribute has a relation to the trust level. + +E.g. Business service providers that offer a validation service for company certificates. + +#### 1.5.9 SOURCE + +Attribute: source + +This defines the company who orginally provided the given certificate (e.g. Company A provided it to Business service provider B, Business service provider B is a trusted validator). This company is also identified by a BPN. + +#### 1.5.10 ID + +Attribute: documentID + +The internal reference id to request a certificate document. + +#### 1.5.11 STATUS + +Attribute: status + +This attribute provides the possibility to define a status to the given certificate. + +Three possible values: active, inactive, pending + +### 1.6 INTERFACE + +*This section is non-normative.* + +In this section the interface / API for the data model is explained. The interface is a main factor for interoperability. + +#### 1.6.1 META DATA CONTROLLER + +For developers implementing the business partner certificate API, it is essential to have access to a list of registered certificate types. This information is necessary to ensure correct spelling and to determine which certificate types are available for use with other API endpoints in this use case. To obtain this information, developers can make an API call to the MetaDataController, using the following endpoint: /api/catena/certificate-types. This call returns a list of all currently registered certificate types. + +In addition to accessing the list of registered certificate types, developers may also need to register a new certificate type. This is necessary when providing new certificates for which the type is not yet known. To register a new certificate type, developers can make an API call to the MetaDataController using the following endpoint (POST): /api/catena/create-certificate-type. This call allows developers to add a new certificate type to the list of registered types, ensuring that it is available for use with other API endpoints in this use case. + +#### 1.6.2 PROVIDE A CERTIFICATE + +In the context of data exchange within the Catena-X dataspace, companies may need to provide their own certificates or the certificates of their partners to other participants. To facilitate this process, a specific API call is available. + +Using the following endpoint (POST): api/catena/certificate/document, companies can provide a certificate document for a legal entity, including all sites assigned to the certificate. This API call allows companies to securely and efficiently share their certificates with other participants in the dataspace, ensuring that all relevant information is included in the document. By providing this API call, the Catena-X dataspace enables seamless and secure data exchange between companies, promoting interoperability and trust in the data exchange process. + +#### 1.6.2 REQUEST CERTIFICATE INFORMATION + +To validate a certificate provided by a company, users can make use of the Catena-X dataspace API. The API provides a range of trust levels, which indicate the level of validation that has been performed on the certificate. These levels include None (no validation check at all), Low (manual validation check done by a human after upload), Medium (certificate provided by a trusted issuer and manually checked), High (automated cross-check via a database, such as TÜV), and Trusted (directly provided by the issuer, such as TÜV). + +To access this information, users can make an API call to the following endpoint: /api/catena/certificate/simple/\{bpn\}/\{certificateType\} . This call returns a true/false value indicating whether the certificate is valid, as well as the certification valid-until date and the trust level. + +In addition to validating certificates, users may also need to request specific certificate information based on the BPN L/S/A. To do this, they can make an API call to the following endpoint: /api/catena/certificate/\{bpn\} this call returns the requested certificate for a legal entity, including all sites assigned to the certificate. By providing these API calls, the Catena-X dataspace enables users to easily verify that a business partner has the necessary certification, promoting trust and confidence in the data exchange process. + +To specify this call - its possible to add the certificate type to get a certicate for a given certificate type: /api/catena/certificate/\{bpn\}/\{certificateType\}. + +The following endpoint: /api/catena/certificate/document/\{cdID\} returns requested certificate document for a legal entity including all sites assigned to a certificate - with the ID the direct and unique document can be requested and found. + +## 2 MAIN CONTENT + +The following rules are minimum requirements and may be supplemented. + +### 2.1. DATA MODEL COMPANY CERTIFICATES + +The following attributes that are described in detail in the terminology chapter and MUST be provided when participating in the use case of company certificates: + +- businessPartnerNumber with the datatype BPNL +- type with the datatype CertificateType +- registrationNumber as a string datatype +- validFrom with the datatype date +- validUntil with the datatype date +- trustLevel with the datatype TrustLevel +- documentID +- status + +There are attributes that are OPTIONAL: + +- areaOfApplication with the datatype string. This is just relevant when there need to be additional details added to a certificate. +- enclosedSites with the datatype List of EcnlosedSites. This becomes a MUST attribute when the certificate is not only relevant for the legal entity but also for one site or more. +- issuer with the datatype BPN. Would be nice to know who issued the certificate but not mandatory. +- validator with the datatype TrustValidator. Typically validates certificate information so that it can be trusted (see also trust levels). + +The data model is implemented according to the API specification that is published in the Tractus-X open source repository: +[BPDM certificate management api](https://github.com/eclipse-tractusx/bpdm-certificate-management/tree/main/doc/api) + +### 2.2. COMPANY CERTIFICATE INTERFACE ENDPOINTS + +The following GET and POST endpoints are MUST - especially for business service providers: + +GET endpoints: + +/api/catena/certificate/\{bpn\} - Get call certificates of a given BPN. +/api/catena/certificate/\{bpn\}/\{certificateType\} - Get a specific certificate by certicate type for a given BPN. +/api/catena/certificate/simple/\{bpn\}/\{certificateType\} - This endpoint checks whether a provided BPN is certified for a specific certificate type. +/api/catena/certificate/document/\{cdID\} - Request a specific / unique certicate document for a given BPN. +/api/catena/certificate-types - Get a list of all currently registered certificate types. + +POST endpoints: + +/api/catena/certificate/document - Provide a specific certicate document for a given BPN. +/api/catena/certificate-types - Register a new certificate type. + +### 2.3 OUT OF SCOPE + +This standardization document does not describe the process and functionality of the lifecycle-management of certificates. + +### 2.4 Conventions for Use Case Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas MUST be followed when providing services or apps for data sharing/consuming. + +#### Additional Details regarding Access Policies + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +#### Additional Details regarding Usage Policies + +In the context of data usage policies (“Usage Policies”), Participants and related services MUST use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile) + +Additionally, respective usage policies MAY include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODLR policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +[BPDM certificate management api](https://github.com/eclipse-tractusx/bpdm-certificate-management/tree/main/doc/api) + +### 3.2 NON-NORMATIVE REFERENCES + +*This section is non-normative.* + +- [BPDM Catena-X Website](https://catena-x.net/en/offers/bpdm) +- CX – 0010 Business Partner Number + +### 3.3 REFERENCE IMPLEMENTATIONS + +*This section is non-normative.* + +## ANNEXES + +### FIGURES + +*This section is non-normative.* + +Intentionally left blank. + +### TABLES + +*This section is non-normative.* + +Intentionally left blank. + +[^1] : For details related to the Pool API, please see standard 0012. +[^2] : For details related to the Business Partner number and the different types, please see standard 0010. +[^3] : For details on the data model and data fields please refer to the 0074 Business Partner Gate API standard. +[^4] : https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf +[^5] : https://catena-x.net/de/standardisierung/catena-x-einfuehren-umsetzen/standardisierung/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0136-UseCasePCF/CX-0136-UseCasePCF.md b/docs/standards/CX-0136-UseCasePCF/CX-0136-UseCasePCF.md new file mode 100644 index 000000000..13dc74662 --- /dev/null +++ b/docs/standards/CX-0136-UseCasePCF/CX-0136-UseCasePCF.md @@ -0,0 +1,647 @@ +# CX-0136 Use Case PCF 1.0.1 + +## ABSTRACT + +This standard focuses on the PCF (Product Carbon Footprint) exchange use case. This includes relevant requirements for: + +- data provider, that want to provide PCF data through Catena-X, +- data consumer, that are want to consume PCF values in Catena-X and +- application developer/ provider supporting the provisioning and consuming of PCF values. + +It will provide information about the used core components as well as the structure of the Digital Twin Registry entry, the data model exchanged and the EDC (Eclipse Dataspace Connector) data structure. + +## FOR WHOM IS THE STANDARD DESIGNED + +## 1 INTRODUCTION + +In an increasingly environmentally conscious world, the standardized exchange of PCF data is of great importance to promote more sustainable and environmentally friendly production and consumption. +The PCF refers to the amount of Greenhouse Gas (GHG) emissions generated during the manufacture, use and disposal of a product. +The exchange of data between companies in Catena-X makes it possible to measure, compare and reduce the environmental impact of products. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +List for which roles the standard is relevant: + +- Data Provider / Consumer +- Business Application Provider + +This documents defines how the PCF exchange in Catena-X takes place and which standards needs to fulfill to be interoperable in the Catena-X Network. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +This document defines the so-called *standardization triangle* for the PCF exchange use case. +Standardization triangle hereby means the mandatory components, data models, APIs etc. that are required to enable the PCF exchange use case. +Additionally, search objects as well as procedures to registering/providing and consuming the data will be defined. + +![Architecture Overview](./assets/ArchitecturalOverview.png) + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +Please refer to: https://catena-x.net/en/catena-x-introduce-implement/certification for the process of conformity assessment and certification. + +Since this document describes a set of standards to be fulfilled, all participants mentioned MUST fulfill all mentioned standards and the respective conformity assessment criteria in addition to the specific criteria mentioned in this document. + +The specific criteria described in this document are describing the usage of the central tools as well as common tools described in the linked standardization documents and therefore compliance should be checked with the tools provided for these components. + +The proof of conformity for a single semantic model is done according to the general rules for proving the conformity of data provided to a semantic model or the ability to consume the corresponding data. + +In terms of conformity the openAPI specification of the application or endpoints being exposed via the EDC or any similar IDS conformant connector **MUST** be checked against the standardized openAPI specification. + +Examples of data assets and contract offer structure in the EDC or any other IDS protocol compliant connector **MUST** correspond to the described structure. + +**Disclaimer: The operating model released by the Catena-X association will define the roadmap, content and scope for the certification process. +This will include the roles, certification and further assessment procedures as well as the rollout phases.** + +### 1.4 EXAMPLES + +For examples how to + +- Request PCF data (with existing material twin including PCF submodel) +- Request PCF data (without existing material Twin or PCF submodel) +- Respond PCF data +- Update PCF data + +please refer to [KIT](https://eclipse-tractusx.github.io/docs-kits/category/pcf-exchange-kit). + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +The following terms are especially relevant for the understanding of the standard: + +**Product Carbon Footprint (PCF)** +The balance of Greenhouse Gas (GHG) emissions along the entire life cycle of a product in a defined application and in relation to a defined unit of use. +The Product Carbon Footprint (PCF) is the most established method for +determining the climate impact of a product. Within the boundary of the Catena-X PCF Rulebook (see [CX-0029 Product Carbon Footprint Rulebook v2.0.0](#211-list-of-standalone-standards)), emissions related to the product use and end-of-life stages are excluded from the PCF. + +**Business Partner Number (BPN)** +A BPN is the unique identifier of a partner within Catena-X. +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +**WBCSD Pathfinder** +At the 9th of November 2021, on the Industry Day at the United Nations +Climate Change Conference (COP26) in Glasgow, UK, the Carbon +Transparency Partnership published the Pathfinder Framework, a guidance +for the calculation and exchange of product-level carbon emissions data +across value chains. + +The Framework was developed jointly by 35 stakeholders from industry and +the broader decarbonization ecosystem, harnessing WBCSD's role as +co-convenor of the Greenhouse Gas Protocol + +The guidance enables companies to better understand carbon emissions on +a granular level, improving business decision-making and helping them +meet their net zero targets. + +**Aspect Model** + +A formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an aspect. + +> **Note** +An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model, see [CX-0003 SAMM Aspect Meta Model v1.1.0](#211-list-of-standalone-standards). + +> **Note** +Aspect models are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 PCF EXCHANGE + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +To participate in the CO2 use-case, the following standard MUST be fulfilled: + +- [CX-0029 Product Carbon Footprint Rulebook v2.0.0](https://catena-x.net/en/standard-library) + +In addition, the following standards are used to support the PCF usecase. Athough they are NOT part of this specification, they are mentioned here, as APIs or other assets provided by them are used within the PCF usecase: + +- [CX-0001 EDC Discovery API v1.0.2](https://catena-x.net/en/standard-library) +- [CX-0002 Digital Twins in Catena-X v2.2.0](https://catena-x.net/en/standard-library) +- [CX-0003 SAMM Aspect Meta Model v1.1.0](https://catena-x.net/en/standard-library) +- [CX-0018 Dataspace Connectivity v3.0.0](https://catena-x.net/en/standard-library) +- [CX-0126 Industry Core: Part Type v1.0.0](https://catena-x.net/en/standard-library) + +#### 2.1.2 ADDITIONAL REQUIREMENTS + +##### 2.1.2.1 On Boarding and IAM + +All participants mentioned under [1.1 AUDIENCE & SCOPE](#11-audience--scope) MUST be onboarded Catena-X members. Data provider and consumer must in addition be participants of the PCF use case. The standards covering this are NOT part of this document but can all be found within the [Catena-X standard repository](https://catena-x.net/en/standard-library). + +##### 2.1.2.2 Fetching EDC Endpoints + +To find the EDC endpoint addresses of related parties in Catena-X, app provider MUST follow the +[CX-0001 EDC Discovery API v1.0.2](#211-list-of-standalone-standards) standard. + +##### 2.1.2.3 Searching for decentralized Digital Twin Registries + +To find decentralized Digital Twin Registries of related parties in Catena-X, app provider MUST +follow the +[CX-0002 Digital Twins in Catena-X v2.2.0](#211-list-of-standalone-standards) Standard. + +##### 2.1.2.4 Registration at the BPN Discovery Service + +> **Note** +Not needed for PCF as the BPN is known by the application. + +##### 2.1.2.5 Registration of the Digital Twin and the PCF Submodel in the Digital Twin Registry + +The PCF use case utilizes Asset Administration Shell (AAS) logic and Material Twins. Therefore Digital Twins SHOULD be registered in the decentralized Digital Twin Registry (DTR). In order to lookup the twin ID, the data provider MUST register the twins with the specificAssetIds ``manufacturerPartId`` and ``digitalTwinType=PartType``. + +> **Note** +The following JSON snippet only illustrates which specificAssetIds have to be used. It *cannot* be used as a copy paste template for twin creation! When setting up a digital twin the data provider has to ensure that these entries are visible to all consumers he wants to address by using the corresponding security mechanisms provided with the digital twin registry. + +```json + "specificAssetIds": [ + { + "key": "manufacturerPartId", + "value": "%%PART-ID%%" + }, + { + "key": "digitalTwinType", + "value": "PartType" + } + ], +``` + +- Data provider also MUST provide an Digital Twin registry API endpoint following the [CX-0002 Digital Twins in Catena-X v2.2.0](#211-list-of-standalone-standards). +- Data provider MUST register the related PCF submodel as shown in the example below. +- The submodel MUST be registered with the ``"idShort": "PCFExchangeEndpoint"`` +- The subprotocolBody for PCF exchange MUST be defined like the following description ``"subprotocolBody": "id=AssetId_of_EDCasset;dspEndpoint=https://some.controlplane.url:7173/api/v1/dsp"`` +- The id added to the subprotocolBody SHOULD be a UUIDv4 +- The ``href`` definition follows [CX-0002 Digital Twins in Catena-X v2.2.0](#211-list-of-standalone-standards) and MUST have the following structure: ``https://edc.data.plane/productIds/mat345`` (URL to use via EDC proxy call to request PCF). + +> **Note** + Replace "edc.data.plane" with the locally needed URL parts to do a EDC proxy call. + +```json +{ + "description": [ + { + "language": "en", + "text": "PCF endpoint for material 'mat345'" + } + ], + "idShort": "PCFExchangeEndpoint", + "identification": "urn:uuid:205cf8d1-8f07-483c-9c5b-c8d706c7d05d", + "semanticId":{ + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.pcf:6.0.0#Pcf" + } + ] + }, + "endpoints": [ + { + "interface": "PCF-1.1", + "protocolInformation": { + "href": "https://edc.data.plane/productIds/mat345", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": ["1.1"], + "subprotocol": "DSP", + "subprotocolBody": "id=c34018ab-5820-4065-9087-416d78e1ab60;dspEndpoint=https://some.controlplane.url:7173/api/v1/dsp", + "subprotocolBodyEncoding": "plain" + } + } + ] +} +``` + +##### 2.1.2.6 Requesting a PCF without an existing Digital Twin or PCF submodel + +In case no Digital Twin or PCF submodel is registered (yet), the asset to use is identified by its type (``{"@id":"cx-taxo:PCFExchange"}``). + +##### 2.1.2.7 EDC Data Asset Structure + +###### 2.1.2.7.1 EDC Data Asset + +The PCF asset MUST be registered as defined below (Management API v3): + +```json +{ + "@context": { + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "odrl": "http://www.w3.org/ ns/odrl/2/", + "dcat": "http://www.w3.org/ns/dcat#", + "dct": "http://purl.org/dc/terms/", + "rdfs": "http://www.w3.org/2000/01/rdf-schema#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "aas-semantics": "https://admin-shell.io/aas/3/0/HasSemantics/" + }, + "@id": "c34018ab-5820-4065-9087-416d78e1ab60", + "@type": "edc:Asset", + "edc:properties": { + "rdfs:label": "PCF Data", + "rdfs:comment": "Endpoint for PCF data", + "cx-common:version": "1.1", + "aas-semantics:semanticId": {"@id":"urn:samm:io.catenax.pcf:6.0.0#Pcf"}, + "edc:contentType": "application/json", + "dct:type": {"@id":"cx-taxo:PcfExchange"} + }, + "edc:dataAddress": { + "edc:type": "HttpData", + "edc:baseUrl": "https://some.url/service", + "edc:proxyBody": "true", + "edc:proxyPath": "true", + "edc:proxyQueryParams": "true", + "edc:proxyMethod": "true", + "edc:contentType": "application/json" + } +} +``` + +The following values MUST be present as EDC asset properties: + +- ``aas-semantics:semanticId``: MUST contain the value: ``"urn:samm:io.catenax.pcf:6.0.0#Pcf"`` +- ``cx-common:version``: MUST contain the value: ``"1.1"`` +- ``dct:type``: MUST follow the schema: ``{"@id":"cx-taxo:PCFExchange"}`` + +The following attributes MUST be set within the ``edc:dataAddress`` section: + +- ``edc:type``: MUST contain the value: ``"edc:HttpData"`` +- ``edc:proxyBody``: MUST contain the value: ``"true"`` +- ``edc:proxyPath``: MUST contain the value: ``"true"`` +- ``edc:proxyQueryParams``: MUST contain the value: ``"true"`` +- ``edc:proxyMethod``: MUST contain the value: ``"true"`` +- ``edc:contentType``: MUST contain the value: ``"application/json"`` + +The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +###### 2.1.2.7.2 EDC Policy Structure + +A participant mentioned under [1.1 AUDIENCE & SCOPE](#11-audience--scope) MUST sign the overall +[Catena-X Terms and Condition](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations) +as well as the [PCF Framework Agreement](https://catena-x.net/fileadmin/user_upload/04_Einfuehren_und_umsetzen/Governance_Framework/231016_Catena-X_Use_Case_Framework_PCF.pdf). +This follows the first SSI setup originally released with Catena-X Rel. 3.2. For more details see the [corresponding standards](https://github.com/catenax-eV/product-standardization-prod/tree/main/standards) which are NOT part of this document. + +The minimum set of **Membership**, the PCF **FrameworkAgreement** and the **UsagePurpose** +MUST to be added to the asset: + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@id": "a343fcbf-99fc-4ce8-8e9b-148c97605aab", + "policy": { + "@context": [ + "https://www.w3.org/ns/odrl.jsonld", + { + "cx-policy": "https://w3id.org/catenax/policy/v1.0.0/" + } + ], + "@type": "Policy", + "profile": "cx-policy:profile2405", + "permission": [ + { + "action": "use", + "constraint": { + "and": [ + { + "leftOperand": "cx-policy:Membership", + "operator": "eq", + "rightOperand": "active" + }, + { + "leftOperand": "cx-policy:FrameworkAgreement", + "operator": "eq", + "rightOperand": "pcf:1.0" + }, + { + "leftOperand": "cx-policy:UsagePurpose", + "operator": "eq", + "rightOperand": "cx.pcf.base:1" + } + ] + } + } + ] + } +} +``` + +For more examples refer [here](https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md). + +###### 2.1.2.7.3 Contract Definition + +Contract definitions of data providers MUST follow the structure below (also defined in [CX-0018 Dataspace Connectivity v3.0.0](#211-list-of-standalone-standards)): + +```json +{ + "@id": "54ef3326-42b2-4221-8c5a-3a6270d54db8", + "edc:accessPolicyId": "a343fcbf-99fc-4ce8-8e9b-148c97605aab", + "edc:contractPolicyId": "a343fcbf-99fc-4ce8-8e9b-148c97605aab", + "edc:assetsSelector":[ + { + "@type": "Criterion", + "edc:operandLeft": "@id", + "edc:operator": "=", + "edc:operandRight": "c34018ab-5820-4065-9087-416d78e1ab60" + } + ] +} +``` + +##### 2.1.2.8 Data Exchange + +As the PCF use case currently supports only asynchronous data exchange, app provider MUST follow the API definition specification in [4.1 PCF EXCHANGE API](#41-pcf-exchange-api). The exchanged data follows the standardized data model defind in [3.1 ASPECT MODEL PCF](#31-aspect-model-pcf). + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### 2.1.3.1 Conventions for Use Case Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas MUST be followed when providing services or apps for data sharing/consuming. + +##### 2.1.3.2 Additional Details regarding Access Policies + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +> **Note** +The access policies for BPNL are not required for the PCF use case as PCF values are exchanged via the request and response process using public endpoints as specified in this specification, see [2.1 PCF EXCHANGE](#21-pcf-exchange). + +##### 2.1.3.3 Additional Details regarding Usage Policies + +In the context of data usage policies (“Usage Policies”), Participants and related services MUST use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +Additionally, respective usage policies MAY include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODLR policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +### 2.2 PCF CALCULATION TOOL INTEGRATION + +This section specifies the integration of PCF calculation solutions in a way that application providers can integrate their solutions in Catena-X. For interoperability, business applications with functionalities for calculation of PCF data need to follow this specification. + +#### 2.2.1 CONTEXT AND ARCHITECTURE FIT FOR PCF CALCULATION TOOL INTEGRATION + +> *This section is non-normative* + +This documents shows + +- how PCF values are calculated in a Catena-X compliant manner +- how PCF data in Catena-X can be transferred between PCF Calculation and PCF Exchange tools +- which standards needs to be fulfilled in context of PCF calculation integration in order to be interoperable in the Catena-X network + +The following scenario describes, how + +- a supplier + - calculates the PCF for his component + - transfers the calculation result to the PCF exchange solution + - provides the PCF to his customer +- a customer + - consumes the PCF from his supplier + - transfers the calculation result from his supplier to the PCF calculation tool + - uses the suppliers calculation result for his PCF calculation + +![PCF Calculation Integration Scenario](./assets/20231115-Catena-X-PCF-Integration-Standard-small.jpg) + +#### 2.2.2 EXAMPLES FOR PCF CALCULATION TOOL INTEGRATION + +> *This section is non-normative* + +Section [2.2.4 PCF DATA FORMAT FOR PCF CALCULATION INTEGRATION](#224-pcf-calculation-data-format) describes the relevant data structure in context of integrating PCF calculationtools in Catena-X. An exemplary data set based on this specification can be found here: [CSV Example](./assets/PCF_Data_Model_Specification_for_Calculation_(Example).csv). + +#### 2.2.3 PCF CALCULATION METHODOLOGY + +> *This section is normative* + +The methodology used for calculating a PCF MUST be conformant with [CX-0029 Product Carbon Footprint Rulebook v2.0.0](#211-list-of-standalone-standards). + +#### 2.2.4 PCF DATA FORMAT FOR PCF CALCULATION INTEGRATION + +> *This section is normative* + +For the integration of PCF calculation solutions, the data format is derived from the standard PCF data model as described in section [ASPECT MODEL PCF](#31-aspect-model-pcf), though in integration context some individual properties are not mandatory but can be specified optionally. + +The data format for the integration of PCF calculation solutions in Catena-X MUST be conformant to the specification defined in [PCF Data Model Specification for Calculation Integration](./assets/PCF_Data_Model_Specification_for_Calculation_Integration.pdf). + +#### 2.2.5 PCF CALCULATION DATA EXCHANGE + +> *This section is non-normative* + +To prove conformity with the PCF calculation tool integration standard, the following criteria SHOULD be applied: + +- The PCF calculation tool SHOULD provide the capability to + - export calculation results in CSV format as described in section [2.2.4 PCF DATA FORMAT FOR PCF CALCULATION INTEGRATION](#224-pcf-calculation-data-format) + - import PCF values in CSV format as described in section [2.2.4 PCF DATA FORMAT FOR PCF CALCULATION INTEGRATION](#224-pcf-calculation-data-format) +- The PCF exchange tool SHOULD provide the capability to + - import calculation results in CSV format as described in section [2.2.4 PCF DATA FORMAT FOR PCF CALCULATION INTEGRATION](#224-pcf-calculation-data-format) + - export PCF values in CSV format as described in section [2.2.4 PCF DATA FORMAT FOR PCF CALCULATION INTEGRATION](#224-pcf-calculation-data-format) + +A template in CSV format can be found here: [CSV Template](./assets/PCF_Data_Model_Specification_for_Calculation.csv) + +## 3 ASPECT MODELS + +> *This section is normative* + +### 3.1 ASPECT MODEL PCF + +#### 3.1.1 INTRODUCTION + +This section describes the PCF data model, which is the basis for the interoperable exchange of PCF values along the supply chain. The PCF data model defines the common format of a PCF value. Applications which allow the exchange of PCF data need to implement the PCF data model as specified as follows. + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The PCF aspect model is written in SAMM 2.1.0 as a modeling language conformant to [CX-0003 SAMM Aspect Meta Model v1.1.0](#211-list-of-standalone-standards) as input for the semantic driven workflow. +Like all Catena-X data models, the PCF model is available in machine-readable format on GitHub conformant to [CX-0003 SAMM Aspect Meta Model v1.1.0](#211-list-of-standalone-standards). + +#### 3.1.3 LICENSE + +The Catena-X PCF data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +> urn:samm:io.catenax.pcf:6.0.0 + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +All different formats of the semantic model can be found in the github repository. + +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.pcf/6.0.0 + +##### 3.1.5.1 RDF TURTLE + +The RDF (Resource Description Framework) Turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.pcf/6.0.0/Pcf.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. These other formats are saved in the "gen" folder in github. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the value-only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.pcf/6.0.0/gen/Pcf-schema.json + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification conformant to [SMT](#62-non-normative-references). + +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.pcf/6.0.0/gen/Pcf.aasx + +##### 3.1.5.4 HTML + +An HTML documentation of the PCF data model can be generated from the RDF Turtle file. + +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.pcf/6.0.0/gen/Pcf.html + +#### 3.1.6 EXAMPLES + +For an exemplary JSON payload based on the PCF data model see [Pcf.json](./assets/Pcf.json). + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +### 4.1 PCF EXCHANGE API + +#### 4.1.1 PRECONDITIONS AND DEPENDENCIES + +The PCF exchange API MUST be published towards the network using a data +asset/contract offer in terms of the DSP protocol. + +Furthermore, the participants of these use case MUST follow the [CX-0001 EDC Discovery API v1.0.2](#211-list-of-standalone-standards) to find the relevant EDC Endpoints. + +#### 4.1.2 API SPECIFICATION + +##### 4.1.2.1 API Endpoints & resources + +The PCF exchange API MUST be implemented as specified in the openAPI +documentation as stated [here](./assets/catena-x-pcf-endpoint-1_1_0.yaml) + +The following two API MUST be provided: + +```text +GET https://{someURL}/productIds/mat345?requestId=123&comment=... +``` + +```text +PUT https://{someURL}/productIds/mat345?requestId=123 +``` + +- The caller's BPN is available through the HTTP header ``Edc-Bpn``. +- When responding to a PCF exchange request the ``requestId`` is *mandatory* in the PUT call. +- When sharing a PCF update the ``requestId`` is *NOT allowed* in the PUT call. + +>**Note** +>Before the PCF data can be pushed back to the requester the data provider needs again to search for the EDC Endpoint of the requester following the EDC Discovery Service API! [CX-0001 EDC Discovery API v1.0.2](#211-list-of-standalone-standards) + +#### 4.1.2.2 Available Data Types + +The PCF exchange API MUST use JSON as the payload is transferred via +HTTP. + +#### 4.1.2.3 API recourses & endpoints + +The HTTP GET and PUT endpoints introduced in this standard SHOULD NOT be +called from a participant of the use case directly. Rather, they MUST be +called via the EDC communication. Therefore, the endpoint MUST be +offered as EDC Data asset following [2.1.2.7 EDC Data Asset Structure](#2127-edc-data-asset-structure). + +##### 4.1.2.4 Error Handling + +HTTP standard response codes MUST be used. + +###### 4.1.2.4.1 Error Messages & Explanation + +The following http codes MUST be defined for HTTP GET endpoint to +request a defined PCF dataset. + +- Code 202: Accepted + +The following http codes MUST be defined for HTTP PUT endpoint to send a +defined PCF dataset back to the quested consumer. + +- Code 200: OK + +## 5 PROCESSES + +> *This section is normative* + +The API wrapper shown in the following sequences is an optional component encapsulating the communication logic. This logic can also be implemented directly within the data exchange app. + +### 5.1 EDC DISCOVERY AND DTR ACCESS + +![EDCDiscoveryAndDTRAccess](./assets/EDCDiscoveryanddDTRAccess.png) + +### 5.2 PCF REQUEST THROUGH AN EXISTING MATERIAL TWIN WITH A CORRESPONDING PCF RESPONSE + +![PCFExchangeThroughAAS](./assets/PCFRequestthroughAAS.png) + +### 5.3 PCF REQUEST WITHOUT AN EXISTING MATERIAL TWIN OR SUBMODEL WITH A CORRESPONDING PCF RESPONSE + +![PCFExchangeWithoutATwin](./assets/PCFRequestWithoutTwinOrSubmodel.png) + +### 5.4 PUSHING A PCF UPDATE WITHOUT AN ADDITIONAL PCF REQUEST + +![PCFUpdatePush](./assets/PCFUpdatePushedThroughEDC.png) + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normative* + +see [2.1.1](#211-list-of-standalone-standards) + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* +> +- How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Currently there is no reference FOSS implementation. For information about available solutions please consult the [PCF Kit](https://eclipse-tractusx.github.io/docs-kits/category/pcf-exchange-kit). + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +[Architectural Overview](./assets/ArchitecturalOverview.png) + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0136-UseCasePCF/assets/20231115-Catena-X-PCF-Integration-Standard-small.jpg b/docs/standards/CX-0136-UseCasePCF/assets/20231115-Catena-X-PCF-Integration-Standard-small.jpg new file mode 100644 index 000000000..cb502acc3 Binary files /dev/null and b/docs/standards/CX-0136-UseCasePCF/assets/20231115-Catena-X-PCF-Integration-Standard-small.jpg differ diff --git a/docs/standards/CX-0136-UseCasePCF/assets/ArchitecturalOverview.png b/docs/standards/CX-0136-UseCasePCF/assets/ArchitecturalOverview.png new file mode 100644 index 000000000..6742f2094 Binary files /dev/null and b/docs/standards/CX-0136-UseCasePCF/assets/ArchitecturalOverview.png differ diff --git a/docs/standards/CX-0136-UseCasePCF/assets/EDCDiscoveryanddDTRAccess.png b/docs/standards/CX-0136-UseCasePCF/assets/EDCDiscoveryanddDTRAccess.png new file mode 100644 index 000000000..edb4fac88 Binary files /dev/null and b/docs/standards/CX-0136-UseCasePCF/assets/EDCDiscoveryanddDTRAccess.png differ diff --git a/docs/standards/CX-0136-UseCasePCF/assets/PCFRequestWithoutTwinOrSubmodel.png b/docs/standards/CX-0136-UseCasePCF/assets/PCFRequestWithoutTwinOrSubmodel.png new file mode 100644 index 000000000..aaef19fd9 Binary files /dev/null and b/docs/standards/CX-0136-UseCasePCF/assets/PCFRequestWithoutTwinOrSubmodel.png differ diff --git a/docs/standards/CX-0136-UseCasePCF/assets/PCFRequestthroughAAS.png b/docs/standards/CX-0136-UseCasePCF/assets/PCFRequestthroughAAS.png new file mode 100644 index 000000000..49de7c3a2 Binary files /dev/null and b/docs/standards/CX-0136-UseCasePCF/assets/PCFRequestthroughAAS.png differ diff --git a/docs/standards/CX-0136-UseCasePCF/assets/PCFUpdatePushedThroughEDC.png b/docs/standards/CX-0136-UseCasePCF/assets/PCFUpdatePushedThroughEDC.png new file mode 100644 index 000000000..cf0132298 Binary files /dev/null and b/docs/standards/CX-0136-UseCasePCF/assets/PCFUpdatePushedThroughEDC.png differ diff --git a/docs/standards/CX-0136-UseCasePCF/assets/PCF_Data_Model_Specification_for_Calculation.csv b/docs/standards/CX-0136-UseCasePCF/assets/PCF_Data_Model_Specification_for_Calculation.csv new file mode 100644 index 000000000..48edc7a58 --- /dev/null +++ b/docs/standards/CX-0136-UseCasePCF/assets/PCF_Data_Model_Specification_for_Calculation.csv @@ -0,0 +1 @@ +id;specVersion;partialFullPcf;precedingPfIds.1;version;created;status;validityPeriodStart;validityPeriodEnd;comment;pcfLegalStatement;companyName;companyIds.1;productDescription;productIds.1;productCategoryCpc;productNameCompany;declaredUnit;unitaryProductAmount;productMassPerDeclaredUnit;exemptedEmissionsPercent;exemptedEmissionsDescription;packagingEmissionsIncluded;boundaryProcessesDescription;geographyCountrySubdivision;geographyCountry;geographyRegionOrSubregion;referencePeriodStart;referencePeriodEnd;crossSectoralStandardsUsed.1.crossSectoralStandard;productOrSectorSpecificRules.1.operator;productOrSectorSpecificRules.1.ruleNames.1.ruleName;productOrSectorSpecificRules.1.otherOperatorName;characterizationFactors;allocationRulesDescription;allocationWasteIncineration;primaryDataShare;secondaryEmissionFactorSources.1.emissionFactorDS;dqi.coveragePercent;dqi.technologicalDQR;dqi.temporalDQR;dqi.geographicalDQR;dqi.completenessDQR;dqi.reliabilityDQR;pcfExcludingBiogenic;pcfIncludingBiogenic;fossilGhgEmissions;biogenicCarbonEmissionsOtherThanCO2;biogenicCarbonWithdrawal;dlucGhgEmissions;luGhgEmissions;aircraftGhgEmissions;packagingGhgEmissions;distributionStagePcfExcludingBiogenic;distributionStagePcfIncludingBiogenic;distributionStageFossilGhgEmissions;distributionStageBiogenicCarbonEmissionsOtherThanCO2;distributionStageBiogenicCarbonWithdrawal;distributionStageDlucGhgEmissions;distributionStageLuGhgEmissions;distributionStageAircraftGhgEmissions;carbonContentTotal;fossilCarbonContent;biogenicCarbonContent diff --git a/docs/standards/CX-0136-UseCasePCF/assets/PCF_Data_Model_Specification_for_Calculation_(Example).csv b/docs/standards/CX-0136-UseCasePCF/assets/PCF_Data_Model_Specification_for_Calculation_(Example).csv new file mode 100644 index 000000000..7d5481f0e --- /dev/null +++ b/docs/standards/CX-0136-UseCasePCF/assets/PCF_Data_Model_Specification_for_Calculation_(Example).csv @@ -0,0 +1,2 @@ +id;specVersion;partialFullPcf;precedingPfIds.1;version;created;status;validityPeriodStart;validityPeriodEnd;comment;pcfLegalStatement;companyName;companyIds.1;productDescription;productIds.1;productCategoryCpc;productNameCompany;declaredUnit;unitaryProductAmount;productMassPerDeclaredUnit;exemptedEmissionsPercent;exemptedEmissionsDescription;packagingEmissionsIncluded;boundaryProcessesDescription;geographyCountrySubdivision;geographyCountry;geographyRegionOrSubregion;referencePeriodStart;referencePeriodEnd;crossSectoralStandardsUsed.1.crossSectoralStandard;productOrSectorSpecificRules.1.operator;productOrSectorSpecificRules.1.ruleNames.1.ruleName;productOrSectorSpecificRules.1.otherOperatorName;characterizationFactors;allocationRulesDescription;allocationWasteIncineration;primaryDataShare;secondaryEmissionFactorSources.1.emissionFactorDS;dqi.coveragePercent;dqi.technologicalDQR;dqi.temporalDQR;dqi.geographicalDQR;dqi.completenessDQR;dqi.reliabilityDQR;pcfExcludingBiogenic;pcfIncludingBiogenic;fossilGhgEmissions;biogenicCarbonEmissionsOtherThanCO2;biogenicCarbonWithdrawal;dlucGhgEmissions;luGhgEmissions;aircraftGhgEmissions;packagingGhgEmissions;distributionStagePcfExcludingBiogenic;distributionStagePcfIncludingBiogenic;distributionStageFossilGhgEmissions;distributionStageBiogenicCarbonEmissionsOtherThanCO2;distributionStageBiogenicCarbonWithdrawal;distributionStageDlucGhgEmissions;distributionStageLuGhgEmissions;distributionStageAircraftGhgEmissions;carbonContentTotal;fossilCarbonContent;biogenicCarbonContent +3893bb5d-da16-4dc1-9185-11d97476c254;2.0.1-20230314;Cradle-to-gate;9c5b94b1-35ad-49bb-b118-8e8fc24abf8;0;2020-03-01T00:00:00Z;Active;2022-01-01T00:00:01Z;2022-12-31T23:59:59Z;Cut-off set 6%;This PCF (Product Carbon Footprint) is for information purposes only. It is based upon the standards mentioned above.;My Corp;urn:bpn:id:BPNL000000000DWF;Ethanol, 95% solution;urn:gtin:4712345060507;011-99000;My Product Name;kilogram;1000.0;0.456;0.0;No exemption;TRUE;Electricity consumption included as an input in the production phase;US-NY;FR;Africa;2022-01-01T00:00:01Z;2022-12-31T23:59:59Z;GHG Protocol Product standard;Other;urn:tfs-initiative.com:PCR:The Product Carbon Footprint Guideline for the Chemical Industry:version:v2.0;NSF;AR6;In accordance with Catena-X PCF Rulebook;cut-off;7.183924;ecoinvent 3.8;100;2.0;2.0;2.0;2.0;2.0;2.0;1.0;0.5;1.0;0.0;0.4;0.3;0.0;0.0;1.5;0.0;0.5;1.0;0.0;1.0;1.1;0.0;2.5;0.1;0.0 diff --git a/docs/standards/CX-0136-UseCasePCF/assets/PCF_Data_Model_Specification_for_Calculation_Integration.pdf b/docs/standards/CX-0136-UseCasePCF/assets/PCF_Data_Model_Specification_for_Calculation_Integration.pdf new file mode 100644 index 000000000..f35e21f31 Binary files /dev/null and b/docs/standards/CX-0136-UseCasePCF/assets/PCF_Data_Model_Specification_for_Calculation_Integration.pdf differ diff --git a/docs/standards/CX-0136-UseCasePCF/assets/Pcf.json b/docs/standards/CX-0136-UseCasePCF/assets/Pcf.json new file mode 100644 index 000000000..c23a69e00 --- /dev/null +++ b/docs/standards/CX-0136-UseCasePCF/assets/Pcf.json @@ -0,0 +1,80 @@ +{ + "specVersion" : "2.0.1-20230314", + "companyIds" : [ "urn:bpn:id:BPNL000000000DWF", "telnet://192.0.2.16:80/", "ftp://ftp.is.co.za/rfc/rfc1808.txt" ], + "extWBCSD_productCodeCpc" : "011-99000", + "created" : "2022-05-22T21:47:32Z", + "companyName" : "My Corp", + "extWBCSD_pfStatus" : "Active", + "version" : 0, + "productName" : "My Product Name", + "pcf" : { + "biogenicCarbonEmissionsOtherThanCO2" : 1.0, + "distributionStagePcfExcludingBiogenic" : 1.5, + "biogenicCarbonWithdrawal" : 0.0, + "distributionStageBiogenicCarbonEmissionsOtherThanCO2" : 1.0, + "extWBCSD_allocationRulesDescription" : "In accordance with Catena-X PCF Rulebook", + "exemptedEmissionsDescription" : "No exemption", + "distributionStageFossilGhgEmissions" : 0.5, + "exemptedEmissionsPercent" : 0.0, + "geographyCountrySubdivision" : "US-NY", + "extTFS_luGhgEmissions" : 0.3, + "distributionStageBiogenicCarbonWithdrawal" : 0.0, + "pcfIncludingBiogenic" : 1.0, + "aircraftGhgEmissions" : 0.0, + "productMassPerDeclaredUnit" : 0.456, + "productOrSectorSpecificRules" : [ { + "extWBCSD_operator" : "PEF", + "productOrSectorSpecificRules" : [ { + "ruleName" : "urn:tfs-initiative.com:PCR:The Product Carbon Footprint Guideline for the Chemical Industry:version:v2.0" + } ], + "extWBCSD_otherOperatorName" : "NSF" + } ], + "extTFS_allocationWasteIncineration" : "cut-off", + "pcfExcludingBiogenic" : 2.0, + "referencePeriodEnd" : "2022-12-31T23:59:59Z", + "extWBCSD_characterizationFactors" : "AR5", + "secondaryEmissionFactorSources" : [ { + "secondaryEmissionFactorSource" : "ecoinvent 3.8" + } ], + "unitaryProductAmount" : 1000.0, + "declaredUnit" : "liter", + "referencePeriodStart" : "2022-01-01T00:00:01Z", + "geographyRegionOrSubregion" : "Africa", + "fossilGhgEmissions" : 0.5, + "distributionStageAircraftGhgEmissions" : 0.0, + "boundaryProcessesDescription" : "Electricity consumption included as an input in the production phase", + "geographyCountry" : "DE", + "extWBCSD_packagingGhgEmissions" : 0, + "dlucGhgEmissions" : 0.4, + "carbonContentTotal" : 2.5, + "extTFS_distributionStageLuGhgEmissions" : 1.1, + "primaryDataShare" : 56.12, + "dataQualityRating" : { + "completenessDQR" : 2.0, + "technologicalDQR" : 2.0, + "geographicalDQR" : 2.0, + "temporalDQR" : 2.0, + "reliabilityDQR" : 2.0, + "coveragePercent" : 100 + }, + "extWBCSD_packagingEmissionsIncluded" : true, + "extWBCSD_fossilCarbonContent" : 0.1, + "crossSectoralStandardsUsed" : [ { + "crossSectoralStandard" : "GHG Protocol Product standard" + } ], + "extTFS_distributionStageDlucGhgEmissions" : 1.0, + "distributionStagePcfIncludingBiogenic" : 0.0, + "carbonContentBiogenic" : 0.0 + }, + "partialFullPcf" : "Cradle-to-gate", + "productIds" : [ "http://www.ietf.org/rfc/rfc2396.txt", "http://www.wikipedia.org", "ftp://ftp.is.co.za/rfc/rfc1808.txt", "telnet://192.0.2.16:80/", "http://www.wikipedia.org" ], + "validityPeriodStart" : "2022-01-01T00:00:01Z", + "comment" : "Comment for version 42.", + "id" : "3893bb5d-da16-4dc1-9185-11d97476c254", + "validityPeriodEnd" : "2022-12-31T23:59:59Z", + "pcfLegalStatement" : "This PCF (Product Carbon Footprint) is for information purposes only. It is based upon the standards mentioned above.", + "productDescription" : "Ethanol, 95% solution", + "precedingPfIds" : [ { + "id" : "3893bb5d-da16-4dc1-9185-11d97476c254" + } ] +} \ No newline at end of file diff --git a/docs/standards/CX-0136-UseCasePCF/assets/catena-x-pcf-endpoint-1_1_0.yaml b/docs/standards/CX-0136-UseCasePCF/assets/catena-x-pcf-endpoint-1_1_0.yaml new file mode 100644 index 000000000..75854d1cb --- /dev/null +++ b/docs/standards/CX-0136-UseCasePCF/assets/catena-x-pcf-endpoint-1_1_0.yaml @@ -0,0 +1,1105 @@ +openapi: 3.0.0 +info: + title: Catena-X-pcf-request-endpoint + version: 1.1.0 +paths: + /productIds/{productId}: + get: + operationId: get_pcf + parameters: + - name: Edc-Bpn + description: The caller's Catena-X BusinessPartnerNumber + example: BPNL0000005AMPL3 + in: header + required: true + schema: + type: string + - name: productId + description: ID of the product/materiual the PCF is requested for + example: urn:id:8534x67 + in: path + required: true + schema: + type: string + - name: requestId + description: >- + ID identifying the call (will be referenced in corresponding PCF + response) + example: 2daa49aa-ee16-4df3-bca3-69ddead40419 + in: query + required: true + schema: + type: string + - name: message + in: query + required: false + description: URL encoded, max 250 chars + example: No%20offset%20included%2C%20please%21 + schema: + type: string + responses: + '202': + description: PCF was accepted. PCF will be sent later via to POST endpoint. + put: + operationId: set_pcf + parameters: + - name: Edc-Bpn + description: The caller's Catena-X BusinessPartnerNumber + example: BPNL0000005AMPL3 + in: header + required: true + schema: + type: string + - name: productId + description: ID of the product/materiual the PCF referring to + example: urn:id:8534x67 + in: path + required: true + schema: + type: string + - name: requestId + description: >- + ID identifying the request call (same as within original PCF + request), if the PUT is responing to a call. Can be dismissed in a + PCF update call. + example: 2daa49aa-ee16-4df3-bca3-69ddead40419 + in: query + required: false + schema: + type: string + requestBody: + description: The requested PCF in WBCSD format + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ProductFootprintResponse' + responses: + '200': + description: '' +components: + schemas: + ProductFootprintResponse: + description: >- + A Product (Carbon) Footprint represents the carbon footprint of a + product with values as specified in the Catena-X PCF Rulebook in + accordance with the WBCSD (World Business Council for Sustainable + Development) Pathfinder framework and the technical specifications for + PCF Data Exchange (Version 2.0.0) from the WBCSD/ PACT initiative. + type: object + properties: + id: + description: >- + Mandatory: The product footprint identifier as specified in the + Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait + specVersion: + description: >- + Mandatory: Version of the product footprint data specification as + defined in the Catena-X PCF Rulebook in accordance with the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text + partialFullPcf: + description: >- + Mandatory: Indicator for partial or full PCF (Product Carbon + Footprint) declaration as specified in the Catena-X PCF Rulebook. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PartialFullPcfCharacteristic + precedingPfIds: + description: >- + Optional: Set of preceding PCF (Product Carbon Footprint) + identifiers without duplicates as specified in the Catena-X PCF + Rulebook in accordance with the WBCSD (World Business Council for + Sustainable Development) Pathfinder framework and the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD/ + PACT initiative. Declared as "optional" in WBCSD, needs to be + covered by application. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PrecedingPfIdsCharacteristic + version: + description: >- + Mandatory: Version of the product (carbon) footprint as specified in + the Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. In Catena-X for example set to "0" per default. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_ProductFootprintVersion + created: + description: >- + Mandatory: Timestamp of the creation of the Product (Carbon) + Footprint as specified in the Catena-X PCF Rulebook in accordance + with the technical specifications for PCF Data Exchange (Version + 2.0.0) from the WBCSD (World Business Council for Sustainable + Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp + extWBCSD_pfStatus: + description: >- + Mandatory: Status indicator of a product (carbon) footprint as + specified in the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. WBCSD specific extension, + in Catena-X for example set to "Active" per default. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PfStatusCharacteristic + validityPeriodStart: + description: >- + Optional: Start of interval during which the product (carbon) + footprint is declared as valid as specified in the Catena-X PCF + Rulebook in accordance with the technical specifications for PCF + Data Exchange (Version 2.0.0) from the WBCSD (World Business Council + for Sustainable Development)/ PACT initiative. If specified, the + validity period start must be equal to or greater than the reference + period end. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp + validityPeriodEnd: + description: >- + Optional: End of interval during which the product (carbon) + footprint is declared as valid as specified in the Catena-X PCF + Rulebook in accordance with the technical specifications for PCF + Data Exchange (Version 2.0.0) from the WBCSD (World Business Council + for Sustainable Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp + comment: + description: >- + Optional: Additional information and instructions related to the + calculation of the product (carbon) footprint as specified in the + Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text + companyName: + description: >- + Mandatory: Name of the product (carbon) footprint data owner as + specified in the Catena-X PCF Rulebook in accordance with the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_NonEmptyStringTrait + companyIds: + description: "Mandatory: Non-empty set of Uniform Resource Names (URN). Each value is supposed to uniquely identify the product (carbon) footprint data owner as specified in the Catena-X PCF Rulebook in accordance with the technical specifications for PCF Data Exchange (Version 2.1.0) from the WBCSD (World Business Council for Sustainable Development)/ PACT initiative. For Catena-X Industry Core compliance the set of URNs must contain at least the Business Partner Number Legal Entity (BPNL) in the specified format urn:bpn:id:BPNL[a-zA-Z0-9]{12}.\_" + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_IdsTrait' + productDescription: + description: >- + Optional: Free-form description of the product as specified in the + Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text + productIds: + description: >- + Mandatory: Non-empty set of product identifiers. Each value is + supposed to uniquely identify the product as specified in the + Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.1.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. In Catena-X productId corresponds with Industry Core + manufacturerPartId. + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_IdsTrait' + extWBCSD_productCodeCpc: + description: >- + Mandatory: UN (United Nations) Product Classification Code (CPC - + Central Classification Code) of a given product as specified the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. WBCSD specific extension, which will probably be + declared as "optional" in a later WBCSD specification version. In + Catena-X for example specified with default value "011-99000". + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text + productName: + description: "Mandatory: Non-empty trade name of a product as specified in the Catena-X PCF Rulebook in accordance with the technical specifications for PCF Data Exchange (Version 2.1.0) from the WBCSD (World Business Council for Sustainable Development)/ PACT initiative. In Catena-X productNameCompany corresponds with Industry Core nameAtManufacturer.\_" + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_NonEmptyStringTrait + pcf: + description: >- + A PCF (Product Carbon Footprint) represents the carbon footprint of + a product and related data as specified in the Catena-X PCF Rulebook + in accordance with the technical specifications for PCF Data + Exchange (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PcfEntity' + pcfLegalStatement: + description: >- + Optional: Option for legal statement/ disclaimer as specified in the + Catena-X PCF Rulebook. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text + required: + - id + - specVersion + - partialFullPcf + - version + - created + - extWBCSD_pfStatus + - companyName + - companyIds + - productIds + - extWBCSD_productCodeCpc + - productName + - pcf + urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait: + type: string + description: >- + The provided regular expression ensures that the UUID is composed of + five groups of characters separated by hyphens, in the form 8-4-4-4-12 + for a total of 36 characters (32 hexadecimal characters and 4 hyphens), + optionally prefixed by "urn:uuid:" to make it an IRI. + pattern: >- + (^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)|(^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$) + urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text: + type: string + description: >- + Describes a Property which contains plain text. This is intended + exclusively for human readable strings, not for identifiers, measurement + values, etc. + urn_samm_io.catenax.pcf_6.0.0_PartialFullPcfCharacteristic: + type: string + description: >- + Characteristic for defining an indicator for partial or full PCF + (Product Carbon Footprint) declaration as specified in the Catena-X PCF + Rulebook. + enum: + - Cradle-to-gate + - Cradle-to-grave + urn_samm_io.catenax.pcf_6.0.0_PrecedingPfId: + description: >- + Entity for defining a preceding PCF (Product Carbon Footprint) + identifier entity as specified in the Catena-X PCF Rulebook in + accordance with the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for Sustainable + Development)/ PACT initiative. + type: object + properties: + id: + description: >- + Mandatory: The product footprint identifier as specified in the + Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait + required: + - id + urn_samm_io.catenax.pcf_6.0.0_PrecedingPfIdsCharacteristic: + description: >- + Characteristic for defining a non-empty set of product (carbon) + footprint identifiers as specified in the Catena-X PCF Rulebook in + accordance with the WBCSD (World Business Council for Sustainable + Development) Pathfinder framework and the technical specifications for + PCF Data Exchange (Version 2.0.0) from the WBCSD/ PACT initiative. + type: array + items: + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PrecedingPfId' + urn_samm_io.catenax.pcf_6.0.0_ProductFootprintVersion: + type: number + minimum: 0 + description: >- + Characteristic for defining a product footprint version as specified in + the Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT initiative. + urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp: + type: string + pattern: >- + -?([1-9][0-9]{3,}|0[0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T(([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\.[0-9]+)?|(24:00:00(\.0+)?))(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))? + description: >- + Describes a Property which contains the date and time with an optional + timezone. + urn_samm_io.catenax.pcf_6.0.0_PfStatusCharacteristic: + type: string + description: >- + Characteristic for defining a status indicator of a product (carbon) + footprint as specified in the Catena-X PCF Rulebook in accordance with + the technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. Enumeration with possible "Active" and "Deprecated". + enum: + - Active + - Deprecated + urn_samm_io.catenax.pcf_6.0.0_NonEmptyStringTrait: + type: string + description: Constraint for ensuring that a string has at least one character. + minLength: 1 + urn_samm_io.catenax.pcf_6.0.0_IdsTrait: + description: >- + Constraint for defining a non-empty set of URIs (Uniform Resource + Identifieres). + type: array + items: + type: string + format: uri + minItems: 1 + urn_samm_io.catenax.pcf_6.0.0_DeclaredUnitCharacteristic: + type: string + description: >- + Unit of analysis of the product with accepted values as specified in the + Catena-X PCF Rulebook in accordance with the technical specifications + for PCF Data Exchange (Version 2.0.0) from the WBCSD (World Business + Council for Sustainable Development)/ PACT initiative. For countable + products/ components/ materials, Catena-X for example adds the unit + "piece" to the value list specified by WBCSD. + enum: + - liter + - kilogram + - cubic meter + - kilowatt hour + - megajoule + - ton kilometer + - square meter + - piece + urn_samm_io.catenax.pcf_6.0.0_StrictlyPositiveDecimalTrait: + type: number + description: Constraint for defining a positive, non-zero decimal. + minimum: 0 + exclusiveMinimum: true + urn_samm_io.catenax.pcf_6.0.0_PositiveDecimalWeightTrait: + type: number + description: Constraint for defining a decimal equal to or greater than zero. + minimum: 0 + exclusiveMinimum: false + urn_samm_io.catenax.pcf_6.0.0_ExemptedEmissionsPercentTrait: + type: number + description: >- + Characteristic for defining the percentage of emissions excluded from a + PCF (Product Carbon Footprint) as specified in the Catena-X PCF Rulebook + in accordance with the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for Sustainable + Development)/ PACT initiative. + maximum: 5 + exclusiveMaximum: false + minimum: 0 + exclusiveMinimum: false + urn_samm_io.catenax.pcf_6.0.0_GeographyCountrySubdivisionTrait: + type: string + description: >- + Constraint for defining a geography country subdivision in compliance to + ISO 3166-2 as specified in the Catena-X PCF Rulebook in accordance with + the technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. + pattern: ([A-Z]{2}-[A-Z0-9]{1,3}|) + urn_samm_io.catenax.pcf_6.0.0_GeographyCountryTrait: + type: string + description: >- + Constraint for defining a geography country conform to ISO 3166CC as + specified in the Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT initiative. + pattern: ([A-Z]{2}) + urn_samm_io.catenax.pcf_6.0.0_GeographyRegionOrSubregionCharacteristic: + type: string + description: >- + Characteristic for defining a list of valid geographic regions as + specified in the Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT initiative. + In Catena-X for example "Global" has been added to the value list. + enum: + - Africa + - Americas + - Asia + - Europe + - Oceania + - Australia and New Zealand + - Central Asia + - Eastern Asia + - Eastern Europe + - Latin America and the Caribbean + - Melanesia + - Micronesia + - Northern Africa + - Northern America + - Northern Europe + - Polynesia + - South-eastern Asia + - Southern Asia + - Southern Europe + - Sub-Saharan Africa + - Western Asia + - Western Europe + - Global + urn_samm_io.catenax.pcf_6.0.0_CrossSectoralStandardsUsedEnumerationCharacteristic: + type: string + description: >- + Characteristic for defining the enumeration of valid accounting + standards used for product carbon footprint calculation as specified in + the Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT initiative. + enum: + - GHG Protocol Product standard + - ISO Standard 14067 + - ISO Standard 14044 + urn_samm_io.catenax.pcf_6.0.0_CrossSectoralStandard: + description: >- + Entity for defining an accounting standard used for product carbon + footprint calculation as specified in the Catena-X PCF Rulebook in + accordance with the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for Sustainable + Development)/ PACT initiative. + type: object + properties: + crossSectoralStandard: + description: >- + Mandatory: Discloses a cross-sectoral standard applied for + calculating or allocating GHG (Greenhouse Gas) emissions as + specified in the Catena-X PCF Rulebook in accordance with the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_CrossSectoralStandardsUsedEnumerationCharacteristic + required: + - crossSectoralStandard + urn_samm_io.catenax.pcf_6.0.0_CrossSectoralStandardSet: + description: >- + Characteristic for defining the list of valid accounting standards used + for product carbon footprint calculation as specified in the Catena-X + PCF Rulebook in accordance with the technical specifications for PCF + Data Exchange (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. + type: array + items: + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_CrossSectoralStandard + urn_samm_io.catenax.pcf_6.0.0_ProductOrSectorSpecificRuleOperator: + type: string + description: >- + Enumeration of PCR (Product Category Rule) operators as specified in the + technical specifications for PCF Data Exchange (Version 2.0.0) from the + WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. WBCSD specific extension for example in Catena-X. + enum: + - PEF + - EPD International + - Other + urn_samm_io.catenax.pcf_6.0.0_RuleName: + description: >- + Name of a rule applied by a specified operator as specified in the + Catena-X PCF Rulebook in accordance with the technical specifications + for PCF Data Exchange (Version 2.0.0) from the WBCSD (World Business + Council for Sustainable Development)/ PACT initiative. + type: object + properties: + ruleName: + description: >- + Name of a rule applied by a specific operator as specified in the + Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_NonEmptyStringTrait + required: + - ruleName + urn_samm_io.catenax.pcf_6.0.0_RuleNamesTrait: + description: >- + Constraint for defining a non-empty set of rule names as specified in + the Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT initiative. + type: array + items: + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_RuleName' + uniqueItems: true + minItems: 1 + urn_samm_io.catenax.pcf_6.0.0_ProductOrSectorSpecificRule: + description: >- + Entity for defining a product or sector specific rule of a product + carbon footprint as specified in the Catena-X PCF Rulebook in accordance + with the technical specifications for PCF Data Exchange (Version 2.0.0) + from the WBCSD (World Business Council for Sustainable Development)/ + PACT initiative. + type: object + properties: + extWBCSD_operator: + description: >- + Mandatory: Operator of PCR (Product Category Rule)/ PSR (Product + Specific Rule) as specified in the technical specifications for PCF + Data Exchange (Version 2.0.0) from the WBCSD (World Business Council + for Sustainable Development)/ PACT initiative. WBCSD specific + extension, in Catena-X for example must always be "Other". + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_ProductOrSectorSpecificRuleOperator + productOrSectorSpecificRules: + description: >- + Mandatory: Product-specific or sector-specific set of rules used for + calculating or allocating GHG (Greenhouse Gas) emissions applied + from the specified operator as specified in the Catena-X PCF + Rulebook in accordance with the technical specifications for PCF + Data Exchange (Version 2.0.0) from the WBCSD (World Business Council + for Sustainable Development)/ PACT initiative. + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_RuleNamesTrait' + extWBCSD_otherOperatorName: + description: >- + Optional: Other operator of PCR (Product Category Rule)/ PSR + (Product Specific Rule) as specified in the technical specifications + for PCF Data Exchange (Version 2.0.0) from the WBCSD (World Business + Council for Sustainable Development)/ PACT initiative. WBCSD + specific extension, in Catena-X for example specified by a default + value. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_NonEmptyStringTrait + required: + - extWBCSD_operator + - productOrSectorSpecificRules + urn_samm_io.catenax.pcf_6.0.0_ProductOrSectorSpecificRuleSet: + description: >- + Characteristic for defining the set of product or sector specific rules + of a product carbon footprint as specified in the Catena-X PCF Rulebook + in accordance with the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for Sustainable + Development)/ PACT initiative. + type: array + items: + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_ProductOrSectorSpecificRule + uniqueItems: true + urn_samm_io.catenax.pcf_6.0.0_CharacterizationFactorsCharacteristic: + type: string + description: >- + Characteristic for defining the characterization factors of a product + carbon footprint as specified in the Catena-X PCF Rulebook in accordance + with the technical specifications for PCF Data Exchange (Version 2.0.0) + from the WBCSD (World Business Council for Sustainable Development)/ + PACT initiative. In Catena-X for example specified by a default value. + enum: + - AR5 + - AR6 + urn_samm_io.catenax.pcf_6.0.0_AllocationWasteIncinerationCharacteristic: + type: string + description: >- + Characteristic for defining the allocation approach used for waste + incineration as specified by the TFS (Together For Sustainability) + initiative. + enum: + - cut-off + - reverse cut-off + - system expansion + urn_samm_io.catenax.pcf_6.0.0_PercentTrait: + type: number + description: Constraint for a decimal number in the range of and including 0 and 100. + maximum: 100 + exclusiveMaximum: false + minimum: 0 + exclusiveMinimum: false + urn_samm_io.catenax.pcf_6.0.0_EmissionFactorDS: + description: >- + Entity for defining an emission factor data source used to calculate a + product carbon footprint as specified in the Catena-X PCF Rulebook in + accordance with the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for Sustainable + Development)/ PACT initiative. + type: object + properties: + secondaryEmissionFactorSource: + description: >- + Mandatory: Emission factor data source used to calculate a product + carbon footprint as specified in the Catena-X PCF Rulebook in + accordance with the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text + required: + - secondaryEmissionFactorSource + urn_samm_io.catenax.pcf_6.0.0_EmissionFactorDSSet: + description: >- + Characteristic for defining a set of emission factor sources used for + calculating a product carbon footprint as specified in the Catena-X PCF + Rulebook in accordance with the technical specifications for PCF Data + Exchange (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. + type: array + items: + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_EmissionFactorDS' + uniqueItems: true + urn_samm_io.catenax.pcf_6.0.0_DqiNumberTrait: + type: number + description: Constraint for defining a decimal between 1 and 3 including. + maximum: 3 + exclusiveMaximum: false + minimum: 1 + exclusiveMinimum: false + urn_samm_io.catenax.pcf_6.0.0_DataQualityIndicators: + description: >- + Characteristic for defining the quantitative data quality indicators of + a PCF (Product Carbon Footprint) as specified in the Catena-X PCF + Rulebook in accordance with the technical specifications for PCF Data + Exchange (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. + type: object + properties: + coveragePercent: + description: >- + Mandatory starting 2025: Percentage of PCF (Product Carbon + Footprint) included in the data quality assessment based on the >5% + emissions threshold as specified in the Catena-X PCF Rulebook in + accordance with the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. In Catena-X for example + set to "100" per default. + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PercentTrait' + technologicalDQR: + description: >- + Mandatory starting 2025: Technological representativeness of the + sources used for PCF (Product Carbon Footprint) calculation based on + weighted average of all inputs representing >5% of PCF emissions. + Specified in the Catena-X PCF Rulebook in accordance with the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_DqiNumberTrait' + temporalDQR: + description: >- + Mandatory starting 2025: Temporal representativeness of the sources + used for PCF (Product Carbon Footprint) calculation based on + weighted average of all inputs representing >5% of PCF emissions. + Specified in the Catena-X PCF Rulebook in accordance with the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_DqiNumberTrait' + geographicalDQR: + description: >- + Mandatory starting 2025: Geographical representativeness of the + sources used for PCF (Product Carbon Footprint) calculation based on + weighted average of all inputs representing >5% of PCF emissions. + Specified in the Catena-X PCF Rulebook in accordance with the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_DqiNumberTrait' + completenessDQR: + description: >- + Mandatory starting 2025: Completeness of the data collected for PCF + (Product Carbon Footprint) calculation based on weighted average of + all inputs representing >5% of PCF emissions. Specified in the + Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_DqiNumberTrait' + reliabilityDQR: + description: >- + Mandatory starting 2025: Reliability of the data collected for PCF + (Product Carbon Footprint) calculation based on weighted average of + all inputs representing >5% of PCF emissions. Specified in the + Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_DqiNumberTrait' + urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Boolean: + type: boolean + description: Represents a boolean value (i.e. a "flag"). + urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait: + type: number + description: 'Only positive emission values (>0) are valid ' + minimum: 0 + exclusiveMinimum: false + urn_samm_io.catenax.pcf_6.0.0_PositiveOrNegativeEmission: + type: number + description: >- + Characteristic for defining (positive or negative) emissions in context + of a PCF (Product Carbon Footprint) as specified by the WBCSD (World + Business Council for Sustainable Development) Pathfinder initiative. + urn_samm_io.catenax.pcf_6.0.0_NegativeEmissionsTrait: + type: number + description: Only negative emission values (<0) are valid. + maximum: 0 + exclusiveMaximum: false + urn_samm_io.catenax.pcf_6.0.0_PcfEntity: + description: >- + Characteristic for defining a PCF (Product Carbon Footprint) as + specified in the Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT initiative. + type: object + properties: + declaredUnit: + description: >- + Mandatory: Unit of analysis of a product in context of the PCF + (product carbon footprint) as specified in the Catena-X PCF Rulebook + in accordance with the technical specifications for PCF Data + Exchange (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. In Catena-X for example + list of valid units includes "piece". + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_DeclaredUnitCharacteristic + unitaryProductAmount: + description: >- + Mandatory: Amount of units contained within a product in context of + the PCF (Product Carbon Footprint) as specified in the Catena-X PCF + Rulebook in accordance with the technical specifications for PCF + Data Exchange (Version 2.0.0) from the WBCSD (World Business Council + for Sustainable Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_StrictlyPositiveDecimalTrait + productMassPerDeclaredUnit: + description: >- + Mandatory: Mass of a product per declared unit in context of the PCF + (Product Carbon Footprint) as specified in the Catena-X PCF + Rulebook. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveDecimalWeightTrait + exemptedEmissionsPercent: + description: >- + Mandatory: Percentage of emissions excluded from PCF (Product Carbon + Footprint) as specified in the Catena-X PCF Rulebook in accordance + with the technical specifications for PCF Data Exchange (Version + 2.0.0) from the WBCSD (World Business Council for Sustainable + Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_ExemptedEmissionsPercentTrait + exemptedEmissionsDescription: + description: >- + Optional: Rationale behind exclusion of specific PCF (Product Carbon + Footprint) emissions as specified in the Catena-X PCF Rulebook in + accordance with the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text + boundaryProcessesDescription: + description: >- + Optional: Processes attributable to each lifecycle stage as + specified in the Catena-X PCF Rulebook in accordance with the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text + geographyCountrySubdivision: + description: >- + Optional: Subdivision of a country which must be an ISO 3166-2 + subdivision code as specified in the Catena-X PCF Rulebook in + accordance with the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_GeographyCountrySubdivisionTrait + geographyCountry: + description: >- + Optional: Two letter country code that must conform to data type ISO + 3166CC as specified in the Catena-X PCF Rulebook in accordance with + the technical specifications for PCF Data Exchange (Version 2.0.0) + from the WBCSD (World Business Council for Sustainable Development)/ + PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_GeographyCountryTrait + geographyRegionOrSubregion: + description: >- + Mandatory: Region according to list as specified in the Catena-X PCF + Rulebook in accordance with the technical specifications for PCF + Data Exchange (Version 2.0.0) from the WBCSD (World Business Council + for Sustainable Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_GeographyRegionOrSubregionCharacteristic + referencePeriodStart: + description: >- + Mandatory: Start of time boundary for which a PCF (Product Carbon + Footprint) value is considered to be representative as specified in + the Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp + referencePeriodEnd: + description: >- + Mandatory: End of time boundary for which a PCF (Product Carbon + Footprint) value is considered to be representative as specified in + the Catena-X PCF Rulebook in accordance with the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp + crossSectoralStandardsUsed: + description: >- + Mandatory: Discloses the cross-sectoral standards applied for + calculating or allocating GHG (Greenhouse Gas) emissions as + specified in the Catena-X PCF Rulebook in accordance with the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_CrossSectoralStandardSet + productOrSectorSpecificRules: + description: >- + Mandatory: Product or sector specific rules applied for calculating + or allocating GHG (Greenhouse Gas) emissions, e.g. PCRs (Product + Category Rules), including operators or publishers and according + rule names as specified in the Catena-X PCF Rulebook in accordance + with the technical specifications for PCF Data Exchange (Version + 2.0.0) from the WBCSD (World Business Council for Sustainable + Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_ProductOrSectorSpecificRuleSet + extWBCSD_characterizationFactors: + description: >- + Mandatory: IPCC (Intergovernmental Panel on Climate Change) version + of the GWP (Global Warming Potential) characterization factors used + for calculating the PCF (Product Carbon Footprint) as specified in + the technical specifications for PCF Data Exchange (Version 2.0.0) + from the WBCSD (World Business Council for Sustainable Development)/ + PACT initiative. WBCSD specific extension, in Catena-X for example + specified by default with value "AR6". + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_CharacterizationFactorsCharacteristic + extWBCSD_allocationRulesDescription: + description: >- + Optional: Allocation rules used and underlying reasoning in context + of a product carbon footprint as specified in the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. WBCSD specific extension, in Catena-X for example + specified by default with value "In accordance with Catena-X PCF + Rulebook". + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text + extTFS_allocationWasteIncineration: + description: >- + Mandatory: Allocation approach used for waste incineration with + energy recovery as specified by the TFS (Together For + Sustainability) initiative. In Catena-X for example must be + specified by value "cut-off". + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_AllocationWasteIncinerationCharacteristic + primaryDataShare: + description: >- + Mandatory starting 2025: Share of primary data in percent as + specified in the Catena-X PCF Rulebook in accordance with the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: '#/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PercentTrait' + secondaryEmissionFactorSources: + description: >- + Mandatory: Emission factors used for the PCF (Product Carbon + Footprint) calculation as specified in the Catena-X PCF Rulebook in + accordance with the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_EmissionFactorDSSet + dataQualityRating: + description: >- + Mandatory starting 2025: Quantitative data quality indicators of a + PCF (Product Carbon Footprint) as specified in the Catena-X PCF + Rulebook in accordance with the technical specifications for PCF + Data Exchange (Version 2.0.0) from the WBCSD (World Business Council + for Sustainable Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_DataQualityIndicators + extWBCSD_packagingEmissionsIncluded: + description: >- + Mandatory: Flag indicating whether packaging emissions are included + in a PCF (Product Carbon Footprint) as specified in the technical + specifications for PCF Data Exchange (Version 2.0.0) from the WBCSD + (World Business Council for Sustainable Development)/ PACT + initiative. WBCSD specific extension, in Catena-X for example value + is "TRUE" per default. + $ref: >- + #/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Boolean + pcfExcludingBiogenic: + description: >- + Mandatory: Product carbon footprint of a product excluding biogenic + emissions as specified in the Catena-X PCF Rulebook in accordance + with the technical specifications for PCF Data Exchange (Version + 2.0.0) from the WBCSD (World Business Council for Sustainable + Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + pcfIncludingBiogenic: + description: >- + Mandatory starting 2025: Product carbon footprint of a product + including biogenic emissions as specified in the Catena-X PCF + Rulebook in accordance with the technical specifications for PCF + Data Exchange (Version 2.0.0) from the WBCSD (World Business Council + for Sustainable Development)/ PACT initiative. Optional value in + current specification version but will be mandatory in future + version. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveOrNegativeEmission + fossilGhgEmissions: + description: >- + Mandatory starting 2025: Emissions from combustion of fossil sources + as specified in the Catena-X PCF Rulebook in accordance with the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. Identical to "pcfExcludingBiogenic", will be removed in + later version. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + biogenicCarbonEmissionsOtherThanCO2: + description: >- + Mandatory starting 2025: GWP (Global Warming Potential) of biogenic + CO2e-emissions in production phase which contain only GHG + (Greenhouse Gas) emissions other than CO2 - excludes biogenic CO2. + For specification see Catena-X PCF Rulebook. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + biogenicCarbonWithdrawal: + description: >- + Mandatory starting 2025: Biogenic carbon content in the product + converted to CO2e as specified in the Catena-X PCF Rulebook in + accordance with the technical specifications for PCF Data Exchange + (Version 2.1.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_NegativeEmissionsTrait + dlucGhgEmissions: + description: >- + Mandatory starting 2025: Direct land use change CO2e emissions in + context of a product carbon footprint as specified in the Catena-X + PCF Rulebook in accordance with the technical specifications for PCF + Data Exchange (Version 2.0.0) from the WBCSD (World Business Council + for Sustainable Development)/ PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + extTFS_luGhgEmissions: + description: >- + Mandatory starting 2025: Land use CO2 emissions in context of a + product carbon footprint as specified by the TFS (Together For + Sustainability) initiative. TFS specific extension. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveOrNegativeEmission + aircraftGhgEmissions: + description: >- + Mandatory starting 2025: GHG (Greenhouse Gas) emissions resulting + from aircraft engine usage for the transport of the product as + specified in the Catena-X PCF Rulebook in accordance with the + technical specifications for PCF Data Exchange (Version 2.0.0) from + the WBCSD (World Business Council for Sustainable Development)/ PACT + initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + extWBCSD_packagingGhgEmissions: + description: >- + Optional: Emissions resulting from the packaging of the product as + specified in the technical specifications for PCF Data Exchange + (Version 2.0.0) from the WBCSD (World Business Council for + Sustainable Development)/ PACT initiative. WBCSD specific extension, + in Catena-X for example value is zero per default. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + distributionStagePcfExcludingBiogenic: + description: >- + Optional: Product carbon footprint for the distribution stage of a + product excluding biogenic emissions as specified in the Catena-X + PCF Rulebook. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + distributionStagePcfIncludingBiogenic: + description: >- + Optional: Product carbon footprint for the distribution stage of a + product including biogenic emissions as specified in the Catena-X + PCF Rulebook. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveOrNegativeEmission + distributionStageFossilGhgEmissions: + description: >- + Optional: Emissions from the combustion of fossil sources in the + distribution stage as specified in the Catena-X PCF Rulebook. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + distributionStageBiogenicCarbonEmissionsOtherThanCO2: + description: >- + Optional: GWP (Global Warming Potential) of biogenic CO2e-emissions + in distribution phase which contain only GHG (Greenhouse Gas) + emissions other than CO2 ? excludes biogenic CO2. For specification + see Catena-X PCF Rulebook. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + distributionStageBiogenicCarbonWithdrawal: + description: >- + Optional: GWP (Global Warming Potential) of biogenic CO2-withdrawal + in distribution stage (biogenic CO2 contained in the product) as + specified in the Catena-X PCF Rulebook. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_NegativeEmissionsTrait + extTFS_distributionStageDlucGhgEmissions: + description: >- + Optional: Direct land use change CO2 emissions during distribution + stage in context of a product carbon footprint as specified in the + Catena-X PCF Rulebook. TFS specific extension. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + extTFS_distributionStageLuGhgEmissions: + description: >- + Optional: Land use CO2 emissions in context of a product carbon + footprint as specified by the TFS (Together For Sustainability) + initiative. TFS specific extension. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveOrNegativeEmission + carbonContentTotal: + description: >- + Mandatory starting 2025: Total carbon content per declared unit in + context of a product carbon footprint as specified in the Catena-X + PCF Rulebook. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + extWBCSD_fossilCarbonContent: + description: >- + Optional: Fossil carbon amount embodied in a product as specified in + the technical specifications for PCF Data Exchange (Version 2.1.0) + from the WBCSD (World Business Council for Sustainable Development)/ + PACT initiative. Must be calculated with kgC (kilogram Carbon) / + declaredUnit equal to or greater zero; WBCSD specific extension, in + Catena-X specified by a calculated value. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + carbonContentBiogenic: + description: >- + Mandatory starting 2025: Biogenic carbon amount embodied in a + product as specified in the Catena-X PCF Rulebook in accordance with + the technical specifications for PCF Data Exchange (Version 2.1.0) + from the WBCSD (World Business Council for Sustainable Development)/ + PACT initiative. Must be calculated with kgC (kilogram Carbon) / + declaredUnit equal to or greater zero. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + distributionStageAircraftGhgEmissions: + description: >- + Optional: GHG (Greenhouse Gas) emissions for the distribution stage + resulting from aircraft engine usage for the transport of the + product as specified in the Catena-X PCF Rulebook in accordance with + the technical specifications for PCF Data Exchange (Version 2.0.0) + from the WBCSD (World Business Council for Sustainable Development)/ + PACT initiative. + $ref: >- + #/components/schemas/urn_samm_io.catenax.pcf_6.0.0_PositiveEmissionsTrait + required: + - declaredUnit + - unitaryProductAmount + - productMassPerDeclaredUnit + - exemptedEmissionsPercent + - geographyRegionOrSubregion + - referencePeriodStart + - referencePeriodEnd + - crossSectoralStandardsUsed + - productOrSectorSpecificRules + - extWBCSD_characterizationFactors + - extTFS_allocationWasteIncineration + - secondaryEmissionFactorSources + - extWBCSD_packagingEmissionsIncluded + - pcfExcludingBiogenic \ No newline at end of file diff --git a/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/CX-0138-UseCaseBehaviourTwinEnduranceEstimator.md b/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/CX-0138-UseCaseBehaviourTwinEnduranceEstimator.md new file mode 100644 index 000000000..c4b591360 --- /dev/null +++ b/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/CX-0138-UseCaseBehaviourTwinEnduranceEstimator.md @@ -0,0 +1,685 @@ +# CX-0138 Use Case Behaviour Twin Endurance Estimator v1.0.1 + +## ABSTRACT + +Behavioral product models, built on a consistent architecture of reusable functional components within ecosystems like Catena-X, unlock a wide range of innovative business ideas and digital services. + +The focus of the 'data-centric and model-centric development and operational support' revolves around the 'digital behaviour twin.' This concept maps products, their functions, attributes, and business metrics by using a shared data model. + +Part of this digital twin involves services providing information about existing or planned vehicles. Stakeholders like automobile clubs or recycler seek specific details, such as a component's expected lifespan. This information is crucial for determining the viability of recycling components. + +This standard focuses on the Endurance Estimator. The Endurance Estimator receives user estimated load, that has been estimated by the service consumer, through the Catena-X network. The user estimated load, combined with additional product knowledge by the service provider, is used to calculate remaining useful life values for specific components. + +## FOR WHOM IS THE STANDARD DESIGNED + +The standard is relevant for the following roles within the scope of the Endurance estimator service: + +- data & service provider/consumer +- business application provider + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +The 1.0 version changed from a triangle (originally CX-0089) to an Use Case Standard and consolidates the contents of the previously independent standards CX-0057, CX-0088, CX-0090 within a single comprehensive standard. + +## 1 INTRODUCTION + +This document acts as a bracket for single standards required to request "Remaining Useful Life (RUL)" data as well as providing a service for its calculation at a component level. Included are APIs to be provided by the service provider and the service requestor, as well as aspect models for the respective payloads being exchanged in an asynchronous pattern leveraging those APIs. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +The standard is relevant for the following roles within the scope of Endurance estimator service: + +- data & consumer provider/consumer +- business application provider + +NOTE: Fulfilling a use-case standard by a data provider/consumer can be done in two ways: A\) purchase a certified app for the use case. In this case the data provider/consumer does not need to proof conformity again and B\) data provisioning/consumption without a certified app for the use case. In this case the data provider/consumer needs to proof conformity with all single standards listed in this document + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +This graphic illustrates the principles architecture of the Endurance estimator Service. + +![architecturalOverviewTriangelEndEstim.drawio.png](./assets/architecturalOverviewTriangelEndEstim.drawio.png) + +The data provider then has user estimated load available and sends it to the service provider via a connector compliant with [CX-0018] (e.g. Tractus-X EDC) as a notification payload. +After the calculation, the results are transfered back to the data provider through this connector. + +This standard contains two aspect models described in detail in Chapter 3. + +- Aspect Model for user estimated loading, acting as the input for the estimation of remaining useful life. (See section 3.1) +- Aspect Model for Remaining Useful Life data, acting as the main output for remaining useful life. (See section 3.2 It also contains the API descriptions for the APIs to exchange requests as well as results of a remaining useful life calculation: +- API Endurance Estimator (contains both API descriptions). (See section 5.1) + +The calculation is asynchronous, therefore both parties involved in a calculation request require to provide API endpoints, as the results are sent back at a later stage and not as part of the HTTP response body. +Since Data Transfer in Catena-X requires IDSA compliance, both parties involved must use an IDSA compliant connector and provision the API endpoints as specific data assets in those connectors. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they are conform with the Catena-X standards. To validate that the +standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). +Since this document describes a set of standards to be fulfilled, participants MUST fulfill all mentioned standards and +the respective conformity assessment criteria in addition to the specific criteria mentioned in this document. +The specific criteria described in this document are describing the usage of the central tools as well as common tools described +in the linked standardization documents and therefore compliance should be checked with the tools provided for these +components. +The Tractus-X Eclipse Dataspace Connector (EDC) is RECOMMENDED to be used as an IDSA compliant connector, as it is the current reference implementation of the IDSA protocol. + +### 1.4 EXAMPLES + +The Endurance estimator can be used in many different contexts. + +Tier-X: The overall product range becomes more attractive in the offer phase when model-based damage calculation is included as a product-related service. + +During the usage phase, OEMs, car dealers and automotive clubs can further interpret the Remaining Useful Life calculation for a vehicle evaluation and offer it as vehicle-related services for their end customers and fleet operators. + +Even during the usage phase, but particularly during the recycling phase, OEMs, Tier-X, automotive clubs, car dealers, insurers, fleet operators and recyclers benefit from residual value analyses of the entire vehicle and its components. + +### 1.5 TERMINOLOGY + +> *This section is non-normativ* + +**Business Partner Number (BPN)** +A BPN is the unique identifier of a partner within Catena-X + +**Eclipse Dataspace Connector (EDC)** +The EDC is a reference implementation of a connector for IDSA conform sovereign data exchange + +**Behavioral Twin** +Behavioural product models, based on a structured and consistent architecture of reusable and standard functional components and applied in a common ecosystem. + +**Notification: Notification** - as described in CX-0023 Notification API v1.2.2, are - in contrast to classical data offers in Catena-X - a way to push data from a sender to a receiver and vice versa. + +**Aspect Model** +: a formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect. + +: Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model. + +: Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +*[Source: Catena-X, CX-0002:v1.2]* + +Usecase specific glossary of used API and SAMM models can be found in the respective sections in this standard document. + +## 2 RELEVANT PARTS OF THE STANDARD "Use Case Behavioral Twin Endurance estimator" + +> *This section is normantive* + +### 2.1 "STANDARDS FOR "Use Case Behavioral Twin Endurance estimator" + +> *This section is normantive* + +As a Service Provider for an Endurance Estimator Service I need to fulfill the following standards in the following contexts: + +- Semantic Model: UserEstimatedLoading (Section 3.1) **MUST** be understood by my service and **MUST** be consumed by my service provider API. +- Semantic Model: Remaining Useful Life (Section 3.2) MUST be provided as part of my communication of the result towards the requestor and/or requesting application +- API: Endurance Estimator (Section 5.1) MUST be followed in terms of all relevant parts for a service provider + +As a Service Requestor or Service Requestor Application I need to fulfill the following standards in the following contexts: + +- Semantic Model: UserEstimatedLoading (Section 3.1) MUST be provided as part of the request for a remaining useful life calculation towards a service operator's API +- Semantic Model: Remaining Useful Life (Section 3.2) MUST be consumable by my connected underlying application. +- API: Endurance estimator (Section 5.1) MUST be followed in terms of all relevant parts for a service requestor. + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +To participate in the Use Case Behavioral Twin Endurance estimator, the following single standards MUST be fulfilled: + +- CX-0018 Dataspace Connectivity 3.0.0 + +#### 2.1.2 DATA REQUIRED + +As a Service Requestor or Service Requestor Application I MUST provide the UserEstimatedLoading in the format of the aspect model described in Section 3.1. +As a Service Provider I MUST provide Remaining useful life information in the format of the aspect model described in Section 3.2. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### Conventions for Use Case Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository. This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas MUST be followed when providing services or apps for data sharing/consuming. + +##### Additional Details regarding Access Policies + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +##### Additional Details regarding Usage Policies + +In the context of data usage policies (“Usage Policies”), Participants and related services MUST use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies MAY include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the ODRL policy repository. + +##### VERSIONING + +Note: Data Assets differentiated only by major version MUST be offered in parallel. The current standard and API versions mark the start of Life Cycle Management in Catena-X operations. Previous versions are dismissed. + +The API version described in this standard document MUST be published in the property https://w3id.org/catenax/ontology/common#version as version X.Y in dcat:Dataset(http://www.w3.org/ns/dcat#). The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. +If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +## 3 ASPECT MODELS + +The following Aspect Models are part of this standard: + +1. UserEstimatedLoading, V 1.0.0, urn:bamm:io.catenax.classified_load_spectrum:1.0.0 +2. RemainingUsefulLife", V1.0.0, urn:bamm:io.catenax.rul:1.0.0##RemainingUsefulLife + +> *This section is normantive* + +### 3.1 ASPECT MODEL "ClassifiedLoadSpectrum" + +The data model UserEstimatedLoading represents the load data of a vehicle component. +The load spectrum is a data set that represents the aggregated loading of a component. +Any kind of loading is covered: loading can be force or torque or revolutions or temperature or event or similar. The load data is classified and counted with specific counting methods. + +This standard defines the format for the counted load data, so that the exchange of load data between different partners is possible. + +#### 3.1.1 INTRODUCTION + +The aspect model comprises basic vehicle data, vehicle status information, previous usage information and future usage information in a structured form in order to estimate the remaining useful life. + +Every data provider of userEstimatedLoading data MUST provide the data conformant to the semantic model specified in this document. The unique identifier of the semantic model specified in this document MUST be used by the data provider to define the semantics of the data being transferred. Every certified business application relying on userEstimatedLoading data MUST be able to consume data conformant to the semantic model specified in this document. This semantic model MUST be made available in the central Semantic Hub. Data consumers and data provider MUST comply with the license of the semantic model. + +In the Catena-X data space userEstimatedLoading data MUST be requested and exchanged via a connector compliant with [CX-0018] (e.g. Tractus-X EDC). The JSON Payload of data providers MUST be conformant to the JSON Schema as specified in this document. + +#### 3.1.2 CONTEXT + +> *This section is non-normative* + +"User estimated loading" is describing the vehicle and the usage of the vehicle. As named, the loading will be estimated from the usage in order to assess the remaining useful life of vehicle respectively the vehicle components. +The usage as well as the vehicle data are general information not specified for a specific component. Previous usage as well as future application are included. + +#### 3.1.3 EXAMPLES + +Example payload in JSON format: + +```json +{ + "vehicleStatus": { + "milage": 123456 + }, + "vehicleData": { + "grossVehicleWeightKG": 1998, + "powerKW": 300, + "energySourceCode": "0008", + "vehicleType": "limousine", + "numberOfPoweredAxles": 2 + }, + + "history": [ + { + "percentage": 25, + "drivingStyle": 80, + "trailerUse": false, + "cityDriving": false, + "hilliness": 80, + "curviness": 60 + }, + { + "percentage": 75, + "drivingStyle": 40, + "trailerUse": false, + "cityDriving": true, + "hilliness": 30, + "curviness": 50 + } + ], + "future": [ + { + "futureScenarioId": 1, + "futureScenario": [ + { + "percentage": 90.0, + "drivingStyle": 30, + "trailerUse": false, + "cityDriving": true, + "hilliness": 10, + "curviness": 50 + }, + { + "percentage": 10.0, + "drivingStyle": 20, + "trailerUse": true, + "cityDriving": true, + "hilliness": 10, + "curviness": 50 + } + ] + }, + { + "futureScenarioId": 2, + "futureScenario": [ + { + "percentage": 100, + "drivingStyle": 20, + "hilliness": 30, + "curviness": 20, + "trailerUse": true, + "cityDriving": false + } + ] + } + ] +} +``` + +#### 3.1.4 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#52-non-normative-references). + +This aspect model is written in BAMM 1.0.0 as a modeling language. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub. + +#### 3.1.5 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.6 IDENTIFIER OF SEMANTIC MODEL + +```text + [Mandatory] +``` + +The semantic model has the unique identifier + +**urn:bamm:io.catenax.user_estimated_loading:1.0.0** + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.7 FORMATS OF SEMANTIC MODEL + +##### 3.1.7.1 RDF Turtle + +```text + [Mandatory] +``` + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.user_estimated_loading/1.0.0/UserEstimatedLoading.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +##### 3.1.7.2 JSON Schema + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.1.7.3 aasx + +```text + [Mandatory] +``` + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#52-non-normative-references)]. + +Note: As soon as the specification V3.0 of the Asset Administration Shell specfication is available +an update will be provided. + +### 3.2 ASPECT MODEL "RemainingUsefulLife" + +#### 3.2.1 INTRODUCTION + +The data model Remaining Useful Life contains the two relevant values to describe the expected remaining life of a vehicle, remaining running distance and remaining operating hours. + +The data model is used for vehicle parts and vehicle components which cannot be visually assessed but need the loading information combined with a damage model to estimate the health of the component. + +#### 3.2.2 CONTEXT + +> *This section is non-normative* + +Remaining useful Life is describing the actual health of a vehicle component. Remaining useful Life is defined for vehicle and vehicle components; the values are “remaining running distance” and “remaining operating hours”. As it is a short-term property, the status of determination is part of the standard. Remaining useful Life is the result of a service determining the health of a vehicle component from the loading the component was subjected to. This loading might before example measured, simulate or estimated, this information on the origin of the loading is part of the standard. + +![remaining_useful_life.png](./assets/remaing_useful_life.png) +*Figure 1: Overview* + +#### 3.2.3 EXAMPLES + +```json +{ +  "remainingOperatingHours": 2500, +  "remainingRunningDistance": 150000, +  "determinationStatus": { +    "date": "2022-06-15T14:23:56Z", +    "operatingHours": 3456.7, +    "mileage": 204000 +  }, +  "determinationLoaddataSource": { +    "informationOriginLoadSpectrum": "loggedOEM" +  } +} +``` + +#### 3.2.4 TERMINOLOGY + +> *This section is non-normative* + +- RemainingRunningDistance: The estimated number of kilometers, the vehicle can drive without expectable failure of the component. This is an integer number, the unit is [km]. +- Remaining operating hours: Estimated number of operating hours of the vehicle without expectable failure of the component. Floating number, unit is [h]. +- determinationLoaddataSource: The remaining life is estimated from the loading the component was subjected to. The loading of the component might be logged during vehicle life or simulated or estimated: this information on the origin is stored here. If available, the URL of the loadspectrum can be stored here. +- determinationStatus : Comprising “date”, “mileage”, “operatingHours”, the timestamp the remainingUsefulLife was calculated and the according mileage and operating hours of the vehicle. +- sourceLoadSpectrum: if available, the URL of the used load spectrum +- informationOriginLoadSpectrum: enumeration of possible loaddata sources: + - "loggedOEM": the data are collected during usage and provided on OEM side + - "measuredOEM": load data are measured on OEM side + - "simulatedOEM": load data are simulated on OEM side + - "loggedSupplier": the data are collected during usage and provided on supplier side + - "measuredSupplier": load data are measured on supplier side + - "simulatedSupplier": load data are simulated on supplier side + - "otherOrigin": any other origin of load data, may be not even a load spectrum + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +#### 3.2.5 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#52-non-normative-references). + +This aspect model is written in BAMM 1.0.0 as a modeling language. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003. + +#### 3.2.6 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.2.7 IDENTIFER OF SEMANTIC MODEL + +The semantic model has the unique identifier: + +urn:bamm:io.catenax.rul:1.0.0##RemainingUsefulLife + +#### 3.2.8 FORMATS OF SEMANTIC MODEL + +##### 3.2.8.1 RDF Turtle + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + +The ttl file can be found here: + +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.rul/1.0.0/RemainingUsefulLife.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +##### 3.2.8.2 JSON Schema + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +##### 3.2.8.3 aasx + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#52-non-normative-references)]. + +Note: As soon as the specification V3.0 of the Asset Administration Shell specfication is available +an update will be provided. + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normantive* + +> *The headings below should only be understood as a suggestion* + +### 4.1 Endurance Estimator API + +Endurance Estimator is a service which estimates the remaining useful life of a vehicle using basic information of the vehicle and the usage. It is aimed for normal customer without access to specific technical vehicle data or logged data stored in the ECU. Usage data are estimated according to application like trailer use and geografical conditions like hilliness. +This document sets the standards for the API for the usage of services which estimates a so-called "remaining useful life value" (RUL-value) using estimated load data (UserEstimatedLoading). + +#### 4.1.1 PRECONDITIONS AND DEPENDENCIES + +The Endurance Estimator service was designed with interoperability in mind, thus the communication in both directions (input/input) fully supports the Catena-X Notification standard. + +The two APIs described support the implementation of the dynamic behavior (i.e., service) of components (e.g., engine, gearbox..) in a digital behavior twin. + +As the process is asynchronous, there are two APIs for different types of participants in the network. + +1. API endpoint to be provided by a Service Provider providing a service to predict the expected lifetime based on user estimated loading. +2. API endpoint to be provided by a Service Requestor application or participant to receive the outcome of such an analysis in an asynchronous manner. + +It is a non-central API, which can be implemented for various components. It relies on a load spectrum as input in order to calculate and return the corresponding RUL value. +The basic idea for the functionality of this API has been derived from CX-0023:v1.2 Notification API. + +As already mentioned in the Introduction, this standard provides the specification of the HTTP REST API endpoint to request (with an according UserEstimatedLoading as input) and sending RUL value via the Catena X Dataspace. Without this API an interoperability between different application, with an aim to receive RUL data, is not given. + +#### 4.1.2 API SPECIFICATION + +##### 4.1.2.1 API Endpoints & resources + +The notification API MUST be implemented as specified in the [[openAPI](https://github.com/catenax-eV/product-standardization-prod/blob/main/standards/CX-0089-APIEndurancePredictor/1.1.0/src/Endurance_Estimator_Notification_openapi.json)] documentation as stated here: + +- POST /api/v1/routine/notification + +In fact, it is OPTIONAL to implement the endpoint paths exactly as described above. The reason is that those endpoints are not called from any supply chain partner directly. Rather, they are called from the Eclipse Dataspace Connector (EDC) or a similar IDSA compliant connector as part of its data assets. In that sense, it is just important to implement endpoints that can process the defined request body and respond with the HTTP status codes and - if required - reply with the defined response body. + +The EDCs/IDSA compliant data assets will act similar to a reverse proxy for the notification endpoints, therefore rather the EDC data assets are of significance, which should be exposed towards Catena-X through the Data Offer Catalogues in the EDC or any other IDSA Protocol compatible connector. + +##### 4.1.2.2 Available Data Types + +The API MUST use JSON as the payload transported via HTTP. +The APIs payload consists of a general notification header and a use-case specific content dictionary. +The request and response are linked by the unique notificationID. + +#### Notification Request Payload Structure + +The main part of the content dictionary MUST follow the main input towards the endurance estimator. + +```json +{ + "header": { + "notificationId": "b1a15145-4533-48e3-8d80-f5b83cc6c201", + "referencedNotificationId": null, + "relatedNotificationId": null, + "senderBPN": "BPNL00000002HCQ9", + "senderAddress": "https://connector2.cp.int.adac.openresearch.com", + "recipientBPN": "https://edc-ocp0900009.apps.c7von4sy.westeurope.aroapp.io/BPNL00000003B2OM", + "recipientAddress": "BPNL00000003B2OM", + "severity": "MINOR", + "status": "SENT", + "targetDate": "2023-02-03T11:58:00.326439Z", + "timeStamp": "2023-02-03T11:58:00.326439Z", + "classification": "RemainingUsefulLifeEstimator", + "respondAssetId": "enduranceEstimatorResult-receipt" + }, + "content": { + "requestRefId": "b1a15145-4533-48e3-8d80-f5b83cc6c201", + "enduranceEstimatorInputs": [ + { + "userEstimatedLoading": { + + } + } + ] + } +} + +``` + +### Notification Response Payload Structure + +The "Remaining Useful Life" as endurance estimator output MUST follow the semantics described in the corresponding model: + +```json +{ + "header": { + "referencedNotificationID": "notification-UUID", + "senderBPN": "BPNL0000000", + "senderAddress": "https://edc-xxxx.xx/BPNL0000000", + "classification": "EnduranceEstimatorResult", + "recipientAddress": "https://connectorxx.com", + "recipientBPN": "BPNL0000000", + "severity": "MINOR", + "status": "SENT", + "targetDate": "target-date", + "timeStamp": "time-stamp", + "respondAssetId": "urn:pilot:service:EndurancePredictorEstimationNotification" + }, + "content": { + "enduranceEstimatorOutputs": [ + { + "remainingUsefulLife": { + + } + } + ] + } + } +``` + +### Notification Response Error Payload Structure + +```json +{ + "header": { + "referencedNotificationID": "notification-UUID", + "senderBPN": "BPNL0000000", + "senderAddress": "https://edc-xxxx.xx/BPNL0000000", + "classification": "EndurancePredictorResult", + "recipientAddress": "https://connectorxx.com", + "recipientBPN": "BPNL0000000", + "severity": "MINOR", + "status": "SENT", + "targetDate": "target-date", + "timeStamp": "time-stamp", + "respondAssetId": "urn:pilot:service:EndurancePredictorEstimationNotification" + }, + "content": { + "type": "Error", + "message": "Error Message", + "enduranceEstimatorOutputs": [] + } + } +``` + +#### 4.1.3 DATA ASSET STRUCTURE + +When using the EDC, the following asset MUST be registered by the specific roles in this process. Other connectors implementing the IDSA Protocol require a similar data asset with the same structure and provisioning towards Catena-X. + +##### 4.1.3.1 Service Consumer + +As an application provider or an data consumer calling an endurance predictor of another participant an API for asynchronous receival of the result is required. +The corresponding data asset **MUST** look like the following: + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#" + }, + "asset": { + "@type": "Asset", + "@id": "enduranceEstimatorResult-receipt", + "properties": { + "dct:type": { + "@id": "EnduranceEstimatorResult" + }, + "cx-common:name": "enduranceEstimatorResult-receipt", + "cx-common:description": "Asset to receive endurance estimator results.", + "cx-common:version": "1.0", + "cx-common:contenttype": "application/json" + } + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "https://{{httpServerWhichOffersTheHttpEndpoint}}/api/v1/routine/notification", + "proxyMethod": "true", + "proxyQueryParams": "true", + "proxyBody": "true" + } +} +``` + +The variable \{\{httpServerWhichOffersTheHttpEndpoint\}\} MUST be set to the HTTP server that offers the endpoint. The path /api/v1/routine/notification MAY align with the HTTP POST path as stated in 2.2.1. +In that sense it can change dependent on the endurance application. + +##### 4.1.3.2 Service Provider + +As an service provider or data provider providing an endpoint for an endurance estimator service, an API for receival of the request including the user estimated loading data is required. +The corresponding data asset **MUST** look like the following: + +```json +{ + "@context": { + "cx-common": "https://w3id.org/catenax/ontology/common#" + }, + "asset": { + "@type": "Asset", + "@id": "enduranceEstimatorRequest-receipt", + "properties": { + "dct:type": { + "@id": "EnduranceEstimatorRequest" + }, + "cx-common:name": "enduranceEstimatorRequest-receipt", + "cx-common:description": "Asset to receive endurance estimator requests incl. load spectrum.", + "cx-common:version": "1.0", + "cx-common:contenttype": "application/json" + } + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "https://{{httpServerWhichOffersTheHttpEndpoint}}/api/v1/routine/notification", + "proxyMethod": "true", + "proxyQueryParams": "true", + "proxyBody": "true" + } +} +``` + +The variable \{\{httpServerWhichOffersTheHttpEndpoint\}\} MUST be set to the HTTP server that offers the endpoint. The path /api/v1/routine/notification MAY align with the HTTP POST path as stated in 2.2.1. +In that sense it can change dependent on the endurance application. + +The variable \{\{httpServerWhichOffersTheHttpEndpoint\}\} MUST be set to the HTTP server that offers the endpoint. The path /api/v1/routine/notification MAY align with the HTTP POST path as stated in 2.2.1. +In that sense it can change dependent on the endurance application. + +#### 4.1.4 ERROR HANDLING + +The following http response codes MUST be defined for HTTP POST endpoint for the Endurance estimator endpoint. + +| Code | Description | +|------|----------------------------------| +| 202 | Accepted | +| 400 | Request body was malformed | + +## 5 REFERENCES + +### 5.1 NORMATIVE REFERENCES + +- CX–0018:v3.0 Dataspace Connectivity +- CX-0023:v1.2 Notification API +- CX-0003:v1.1 SAMM Aspect Meta Model + +### 5.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +- [CX_Operating_Modelv2.1_final.pdf (catena-x.net)](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf) + +### 5.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/assets/Endurance_Estimator_Notification_openapi.json b/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/assets/Endurance_Estimator_Notification_openapi.json new file mode 100644 index 000000000..5237052a2 --- /dev/null +++ b/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/assets/Endurance_Estimator_Notification_openapi.json @@ -0,0 +1,316 @@ +{ + "openapi": "3.0.2", + "info": { + "title": "[BTG] Service Gateway", + "version": "v1" + }, + "paths": { + "/api/v1/routine/notification": { + "post": { + "tags": [ + "Engineering Services" + ], + "summary": "Notification API", + "description": "**Execution of Engineering Service via Notification**\n \n Notification Endpoint is used to Execute Engineering Services like Endurance Estimator of Component.\n\n**Request Schema:**\n\n **Input payload** : One or more BAMM model Load spectrum in content input payload.\n\n***Note***: *JSON Payload should be have 'header' and 'content' where we have load spectrum*\n\n**Response Schema:**\n\n **status_codes** : Status code of send notification and response content of it.\n\n\n", + "operationId": "execute_engineering_service_via_notification_api_v1_routine_notification_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestNotification" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + }, + "202": { + "description": "Execution of Engineering Services Endurance Predictor/Health Indicator job in progress..", + "content": { + "application/json": { + "example": { + "Message": "Accepted" + } + } + } + }, + "400": { + "description": "Validation Error", + "content": { + "application/json": { + "example": { + "detail": "Uploaded load collective payload missed: 'field name' are mandatory fields." + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + }, + "500": { + "description": "Server error - Abstract information on what has gone wrong", + "content": { + "application/json": { + "example": { + "detail": "Issue in connecting to datalake service" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "Body_perform_damage_calculation_api_v1_routine_calculate_damage_post": { + "title": "Body_perform_damage_calculation_api_v1_routine_calculate_damage_post", + "type": "object", + "properties": { + "load_collective_files": { + "title": "Load Collective Files", + "type": "array", + "items": { + "type": "string", + "format": "binary" + } + } + } + }, + "Body_perform_endurance_estimator_api_v1_routine_calculate_endurance_estimator_post": { + "title": "Body_perform_endurance_estimator_api_v1_routine_calculate_endurance_estimator_post", + "type": "object", + "properties": { + "load_collective_file": { + "title": "Load Collective File", + "type": "string", + "format": "binary" + } + } + }, + "Body_perform_endurance_predictor_calculation_api_v1_routine_calculate_endurance_predictor_post": { + "title": "Body_perform_endurance_predictor_calculation_api_v1_routine_calculate_endurance_predictor_post", + "type": "object", + "properties": { + "load_collective_files": { + "title": "Load Collective Files", + "type": "array", + "items": { + "type": "string", + "format": "binary" + } + } + } + }, + "Body_perform_health_indicator_calculation_api_v1_routine_calculate_health_indicator_post": { + "title": "Body_perform_health_indicator_calculation_api_v1_routine_calculate_health_indicator_post", + "type": "object", + "properties": { + "load_collective_files": { + "title": "Load Collective Files", + "type": "array", + "items": { + "type": "string", + "format": "binary" + } + } + } + }, + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": { + "$ref": "#/components/schemas/ValidationError" + } + } + } + }, + "RequestNotification": { + "title": "RequestNotification", + "type": "object", + "properties": { + "header": { + "title": "Header", + "type": "object", + "default": { + "notificationID": "f8ca7d3c-xxxx-4879-a170-a24cxxxxxxxxx", + "senderBPN": "Sender BPN", + "senderAddress": "Sender Connector IP Address", + "recipientAddress": "https://edc-ocp0900009.apps.c7von4sy.westeurope.aroapp.io", + "recipientBPN": "BPNL00000003B2OM", + "severity": "MINOR", + "status": "SENT", + "targetDate": "2022-11-24T22:07:02.611048800Z", + "timeStamp": "2022-11-24T11:24:36.744320Z", + "classification": "RemainingUsefulLifeEstimator", + "respondAssetId": "enduranceEstimatorResult-receipt" + } + }, + "content": { + "title": "Content", + "type": "object", + "default": { + "requestRefId": "f8ca7d3c-xxxx-4879-a170-a24cxxxxxxxxx", + "enduranceEstimatorInputs": [ + { + "userEstimatedLoading": { + "vehicleStatus": { + "mileage": 120500 + }, + "vehicleData": { + "grossVehicleWeightKG": 1500, + "powerKW": 130, + "energySourceCode": "0001", + "vehicleType": "Limousine", + "numberOfPoweredAxles": 2 + }, + "history": [ + { + "percentage": 26, + "drivingStyle": 30, + "hilliness": 10, + "curviness": 20, + "trailerUse": true, + "cityDriving": false + }, + { + "percentage": 27, + "drivingStyle": 40, + "hilliness": 30, + "curviness": 50, + "trailerUse": true, + "cityDriving": false + }, + { + "percentage": 47, + "drivingStyle": 50, + "hilliness": 40, + "curviness": 60, + "trailerUse": true, + "cityDriving": true + } + ], + "future": [ + { + "futureScenarioId": 1, + "futureScenario": [ + { + "percentage": 30, + "drivingStyle": 20, + "trailerUse": false, + "cityDriving": false, + "hilliness": 30, + "curviness": 20 + }, + { + "percentage": 10, + "drivingStyle": 60, + "trailerUse": false, + "cityDriving": false, + "hilliness": 60, + "curviness": 60 + }, + { + "percentage": 25, + "drivingStyle": 30, + "trailerUse": false, + "cityDriving": true, + "hilliness": 10, + "curviness": 50 + }, + { + "percentage:35.0": null, + "drivingStyle": 20, + "trailerUse": false, + "cityDriving": true, + "hilliness": 10, + "curviness": 30 + } + ] + }, + { + "futureScenarioId": 2, + "futureScenario": [ + { + "percentage": 28, + "drivingStyle": 20, + "trailerUse": true, + "cityDriving": false, + "hilliness": 30, + "curviness": 20 + }, + { + "percentage": 36, + "drivingStyle": 80, + "trailerUse": false, + "cityDriving": false, + "hilliness": 80, + "curviness": 60 + }, + { + "percentage": 36, + "drivingStyle": 40, + "trailerUse": false, + "cityDriving": true, + "hilliness": 30, + "curviness": 50 + } + ] + } + ] + } + } + ] + } + } + }, + "description": "Sample Request Notification payload." + }, + "ValidationError": { + "title": "ValidationError", + "required": [ + "loc", + "msg", + "type" + ], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": { + "type": "string" + } + }, + "msg": { + "title": "Message", + "type": "string" + }, + "type": { + "title": "Error Type", + "type": "string" + } + } + } + } + } +} \ No newline at end of file diff --git a/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/assets/architecturalOverviewTriangelEndEstim.drawio.png b/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/assets/architecturalOverviewTriangelEndEstim.drawio.png new file mode 100644 index 000000000..7d77b7a02 Binary files /dev/null and b/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/assets/architecturalOverviewTriangelEndEstim.drawio.png differ diff --git a/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/assets/remaing_useful_life.png b/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/assets/remaing_useful_life.png new file mode 100644 index 000000000..849b73f4d Binary files /dev/null and b/docs/standards/CX-0138-UseCaseBehaviourTwinEnduranceEstimator/assets/remaing_useful_life.png differ diff --git a/docs/standards/CX-0139-InformationasaServiceExternalDataProvider/CX-0139-InformationasaServiceExternalDataProvider.md b/docs/standards/CX-0139-InformationasaServiceExternalDataProvider/CX-0139-InformationasaServiceExternalDataProvider.md new file mode 100644 index 000000000..50bf1dc05 --- /dev/null +++ b/docs/standards/CX-0139-InformationasaServiceExternalDataProvider/CX-0139-InformationasaServiceExternalDataProvider.md @@ -0,0 +1,122 @@ +# CX-0139 Information as a Service - External Data Provider v1.0.0 + +## ABSTRACT + +Catena-X as an open and collaborative Data-Ecosystem and the current Operating Model defines Data Provider and Data Consumer as Members of an existing Value Chain, providing and consuming Operative Data necessary for their Business Relation. +Business Application Provider are running Services, enabling and supporting these Business Processes and Collaboration, the integrated Information-Sharing is immanent and not a separate Commercial Subject. These Services are related to specific Use Cases and Standards defined in the Catena-X Framework. +Beside and beyond these kinds of sharing of Operative Data, Businesses need many Third-Party Information e.g., Material, Business Partner, Standards, Environment, Prices etc..., as well as Automotive Value Chain Processes (reflected in Catena-X Use Cases) need Third Party Information. +These are Information collected, refined (evaluated, qualified, analysed, transformed etc.) and provided by Third-Party Information Providers (Information aaS). The Source of this Information resides outside the Catena-X Ecosystem, the Information aaS-Provider has a Commercial Model for this Service. +For Information from inside the Catena-X Ecosystem the Standards are defined in existing and future Use Cases. +Information from outside the Catena-X Ecosystem is not covered by existing Standards and is matter to this Standard. + +## FOR WHOM IS THE STANDARD DESIGNED + +See Chapter 1.1. Audience and Scope + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +Not applicable + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This Standard is relevant for the following audience: + +Core Service Provider +Data Provider / Consumer +Business Application Provider + +The Scope of this Standard is to enable Third-Party Information Provider to deliver Data from outside Catena-X inside Catena-X. This Standard is generic to every Use Case and qualifies Information aaS Provider as a potential Data Provider for a Use Case defined Business Application. The Data can be delivered only to a specific Use Case within Catena-X, realised in an certified Business Application. +By this way the Standard enables Third-Party Information Provider to deliver Data from outside Catena-X inside Catena-X and at the same time limits Data Delivery to existing Use Cases, avoiding Violations or Bypasses of existing Standards and Regulations within Catena-X. For this reason the Business Application Provider and the Third-Party Information Party Provider have a special responsibility based on this standard. The Business Application Provider is responsible for data governance with respect to Catena-X standards for the respective Use Case and Business Application. Both Business Application Provider and Third-Party Information Provider are responsible to respect existing license agreements that may be related to the provisioned data. +Not in Scope of this Standard is a Data Provider who deliver data from inside Catena-X to a Data Consumer inside Catena-X, this is regulated e.g., with CX-0007 Process Specification Minimal Data Provider Service Offering v1.0.2. +Not in Scope of this Standard is a Data Provider who deliver Data from inside Catena-X to a Data Consumer outside Catena-X, this Use Case requieres separate Regulation. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +The Establishment of various Industry Networks (such as Catena-X) has increased the need to establish Data Standards across the entire Automotive Value Chain and to promote industry-wide, international Data Exchange. This Data Exchange is primarily focused on Operative Data immanent to the entire Value Chain and necessary for Business Processes and Relations. +Beside and beyond these kinds of sharing of Operative Data, Businesses need many Third-Party Information e.g., Material, Business Partner, Standards, Environment, Prices etc..., as well as Automotive Value Chain Processes (reflected in Catena-X Use Cases) need Third-Party Information. +These are Information collected, refined (evaluated, qualified, analysed, transformed etc.) and provided by Third-Party Information Providers (Information aaS). The Source of this Information resides outside the Catena-X Ecosystem, the Information aaS-Provider has a Commercial Model for this Service. +The provision of any information from a Third-Party Information Provider can´t bypass existing standards and regulations from the entire Catena-X framework related to the given Catena-X Use Case.Therefore a Third-Party Information Provider can´t provide Infromation as it is, but only to a certified Business Application Provider for a certified Business Application. +The Third-Party Information Provider must be certified for this Standard to provide Data. The Business Application Provider and the Business Application must be certified for the Standards related to the relevant Use Case. +Example: +For the Use Case Country Risk in BPDM Value-Added Services the Business Application Provider who provides the Service and the Business Application must be cerified for "CX-0081 Country Risk API". The Third-Party Information Provider, who provides Information as a Service to this Business Application Provider and the Business Application, must be certified for this new Standard "CX-0139 Information as a Service - External Data Provider" + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +### 1.4 EXAMPLES + +For the Use Case Country Risk in BPDM Value-Added Services the Business Application Provider who provides the Service and the Business Application must be cerified for "CX-0081 Country Risk API". The Third-Party Information Provider, who provides Information as a Service to this Business Application Provider and the Business Application, must be certified for this new Standard "CX-0139 Information as a Service - External Data Provider" + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +Third-Party Information Provider +A Third-Party Information Provider collect, refine (evaluate, qualify, analyse, transforme etc.) differentkind of Information (e.g., Material, Weather, Business Partner, Prices etc.) and provide this Information to a Data Consumer (Information aaS). +The Source of this Information resides outside as well as inside the Catena-X Ecosystem, the Information aaS-Provider has a Commercial Model for this Service. + +External Data Provider +A External Data Provider is a Third-Party Information Provider who provides Information where the Source of this Information resides outside the Catena-X Ecosystem. + +## 2 MAIN CONTENT + +> *This section is normative* + +This standard differentiates between two roles: Requirements for the `Business Application Provider` who receives and shares Third-Party Information and their Use Cases and their `Third-Party Information Provider`. + +To get certified as a `Business Application Provider` who receives and shares Third-Party Information, the Business Application Provider MUST: + +- document that he receives Information for a certified Business Application. +- document that he receives Information from a certified Third-Party Information Provider +- document the license agreement, that he is entitled and by what terms, for the received and (through the Catena-X data ecosystem) shared Information. + +To get certified as a `Third-Party Information Provider`, the Third-Party Information Provider MUST: + +- document that he provides Information to a certified Business Application Provider and for a certified Business Application. +- document the license agreement, that he is entitled and by what terms, for the provided Information if applicable. If the provided Information is publicly available without a third-party agreement a license agreement is not applicable. +- Third-Party Information Provider MUST NOT be certified for existing Standards for the related Use Case in his role as a Third-Party Information Provider. + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +Not applicable + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +Not applicable + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0141-HealthIndicatorUseCase/CX-0141-HealthIndicatorUseCase.md b/docs/standards/CX-0141-HealthIndicatorUseCase/CX-0141-HealthIndicatorUseCase.md new file mode 100644 index 000000000..d6208a913 --- /dev/null +++ b/docs/standards/CX-0141-HealthIndicatorUseCase/CX-0141-HealthIndicatorUseCase.md @@ -0,0 +1,190 @@ +# CX-0141 Use Case Behaviour Twin Health Indicator v1.0.0 + +## ABSTRACT + +Behavioral product models, built on a consistent architecture of reusable functional components within ecosystems like Catena-X, unlock a wide range of innovative business ideas and digital services. + +The focus of the 'data-centric and model-centric development and operational support' revolves around the 'digital behaviour twin'. This concept maps products, their functions, attributes, and business metrics using a shared data model. + +Part of this digital twin involves dynamic services providing real-time information about existing or planned vehicles. Stakeholders like automobile clubs or recycler seek specific details, such as a component's expected lifespan. This information is crucial for determining the viability of recycling components. + +This standard focuses on the Health Indicator Use Case. The Health Indicator recieves dynamic input data, that has been recorded in the vehicle, through the Catena-X network. The input data, combined with additional product knowledge by the service provider, is used to calculate precise health indicator values for specific components. + +## FOR WHOM IS THE STANDARD DESIGNED + +The standard is relevant for the following roles within the scope of the Health Indicator: + +- data & service provider/consumer +- business application provider + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +## 1 INTRODUCTION + +This document acts as a umbrella for single standards required to request "Health Indicator" data as well as providing a service for its calculation at a component level. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +The standard is relevant for the following roles within the scope of a Health Indicator service + +- data provider/consumer +- business application provider + +NOTE: Fulfilling a use case standard by a data provider/consumer can be done in two ways: A\) Purchase a certified app for the +use case. In this case the data provider/consumer does not need to proof conformity again and B\) Data provisioning/consumption without a certified app for the use case. In this case the data provider/consumer needs to proof conformity with +all single standards listed in this document. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +This graphic illustrates the principles architecture of the Health Indicator use case. + +![architecture overview](./assets/architecture_overview_knowledge_agent.drawio.png) + +Since Data Transfer in Catena-X requires IDSA compliance, both parties involved must use an IDSA compliant connector and +provision the API endpoints as specific data assets in those connectors. + +The Knowledge Agent functionality for the Dataspace Connector is required. This is defined in CX-0084:v1.2 Federated Queries in Data Spaces. + +A standard for a semantic-driven and state-of-the-art compute-to-data architecture for Catena-X is the so-called Knowledge Agents (KA) approach. It builds on well-established W3C-standards of the semantic web. + +Depending on your role, you must provide the following parts of this standard: + +- **all**: + - running Knowledge Agent Dataspace Connector extensions +- **data provider** and **service requester**: + - bindings for load spectra to the knowledge graph, ideally by using a binding agent (see Binding Layer and related examples in CX-0084:v1.2) + - graph asset, which describes and offers the data bindings in a Knowledge Agent compatible way (policies may also be required) + - an own HI skill or a access to a remote skill +- **service provider** + - bindings for a health indicator service (see cx-behaviour:VehicleHealth within the [behaviour ontology](https://w3id.org/catenax/ontology/behaviour)) to the knowledge graph, ideally by using a binding agent + - graph asset, which describes and offers the service bindings in a Knowledge Agent compatible way (policies may also be required) + +If the service requester requests HI values, he invokes the HI skill and provides a vehicle identification number to it. This can also be done for multiple vehicles at once in a batch mode. The data bindings and the service provider are resolved by the Knowledge Agent. Then, the data are transferred to the service provider via Knowledge Agent. There, the HI values are calculated and passed back to the requester. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to proof, that they conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). +Since this document describes a set of standards to be fulfilled, participants MUST fulfill all mentioned standards and +the respective conformity assessment criteria in addition to the specific criteria mentioned in this document. +The specific criteria described in this document are describing the usage of the central tools as well as common tools described in the linked standardization documents and therefore compliance should be checked with the tools provided for these components. +The Tractus-X EDC (Eclipse Dataspace Connector) is RECOMMENDED to be used as an IDSA compliant connector, as it is the current +reference implementation of the IDSA protocol. + +### 1.4 EXAMPLES + +The Health Indicator can be used in many different contexts. + +OEM, TIER-X: During the usage phase, health indicators provide a continuous and comprehensive view of the condition of products in the field. Abnormalities, possible defects or failures can be detected reliably and early on. This provides the time advantage to initiate countermeasures in good time. During development phase, health indicators can be used to bring more mature products into series production. + +TIER-X: The overall product range becomes more attractive in the offer phase, when the definition of health indicators as a product-related service is included. + +Workshops: In case of failure analysis and repair, workshops benefit from an extended range of data on vehicle condition and its components. In return, service providers can standardize and facilitate access to the OEM. + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +- **Business Partner Number (BPN):** A BPN is the unique identifier of a partner within Catena-X +- **Tractus-X EDC (Eclipse Dataspace Connector):** The Tractus-X EDC is a reference implementation of a connector for IDSA conform sovereign data exchange +- **Behaviour Twin:** Behavioral product models, based on a structured and consistent architecture of reusable and standard functional components and applied in a common ecosystem. +- **Knowledge Agent (KA):** The so-called Knowledge Agents (KA) approach. It builds on well-established W3C-standards of the semantic web, such as OWL, SPARQL, SHACL, RDF etc. and makes these protocols usable to formulate powerful queries to the data space. Those queries can be used to answer business questions directly (comparable to a search engine) or they can be embedded in apps to include query results into workflows with more advanced visualization. +- **Matchmaking Agent:** This component supports SparQL to traverse the federated data space as a large data structure. It interacts with the Dataspace Connector. + The provider's Matchmaking Agent will be activated by its Dataspace Connector. Therefore, the Dataspace Connector must offer a Graph Asset (variant of ordinary data assets in the Catena-X Dataspace Connectivity standard). + The consumer's Matchmaking Agent interacts with its Dataspace Connector to negotiate and perform the transfer of Sub-Skills to other dataspace participants. + The Matchmaking Agents are matching the (sub)graphs and negotiate appropriated graph assets with the partner Dataspace Connectors. +- **Binding Agent:** The Binding Agent is a restricted version of the Matchmaking Agent (subset of OWL/SparQL, e.g., without federation) which is just focused on translating Sub-Skills of a particular business domain (Bill-Of-Material, Chemical Materials, Production Sites, etc.) into proper SQL- or REST based backend system calls. Implementation details: For data bindings, OnTop is used. For service bindings, RDF4J is used. +- **Ontology:** The ontology is a formal representation of knowledge that captures concepts, relationships, and properties. It allows a shared understanding and reasoning about the respective domain. It must be hosted in a way that all participants can access it. Currently, the ontology is hosted at GitHub. + +## 2 RELEVANT PARTS OF THE STANDARD "Use Case Behaviour Twin Health Indicator" + +### 2.1 STANDARDS FOR "Use Case Behaviour Twin Health Indicator" + +> *This section is normative* + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +To participate in the Use Case Behaviour Twin Health Indicator, the following single standards MUST be fulfilled: + +- CX-0018:v3.0 Dataspace Connectivity +- CX-0067:v1.1 Ontology Models to realize federated query in Catena-X (only if using the Knowledge Agent) +- CX-0084:v1.2 Federated Queries in Data Spaces (only if using the Knowledge Agent) + +#### 2.1.2 DATA REQUIRED + +As a service requester or service requester application I MUST provide Health Indicator Input data (bound to the knowledge graph). +As a Service Provider I MUST provide Health indicator output information (service, bound to the knowledge graph). + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### KNOWLEDGE AGENT SPECIFIC REQUIREMENTS + +If you are engaged as a data provider, you MUST mount your data source to the federated knowledge graph as Graph Asset. Beside the policy and contract definition, a Graph Asset registration is needed. +As a service provider you MUST make the service available as part of the federated knowledge graph, a Graph Asset pointing to your Remoting Agent endpoint is needed. + +##### Conventions for Use Case Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository. This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas MUST be followed when providing services or apps for data sharing/consuming. + +##### Additional details regarding Access Policies + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number. + +- Membership +- BPNL + +##### Additional Details regarding Usage Policies + +In the context of data usage policies ("Usage Policies"), Participants and related services MUST use the following policy rules: + +- Use Case Framework ("FrameworkAgreement") +- at least one use case purpose ("UsagePurpose") from the above mentioned ODRL policy repository. + +Additionally, respective usage policies MAY include the following policy rule: + +- Reference Contract ("ContractReference"). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are provided via the ODRL policy repository. + +##### Versioning + +Note: Data Assets differentiated only by major version MUST be offered in parallel. The current standard and API versions mark the start of Life Cycle Management in Catena-X operations. Previous versions are dismissed. + +The API version described in this standard document MUST be published in the property [https://w3id.org/catenax/ontology/common#version](https://w3id.org/catenax/ontology/common#version) as version X.Y in dcat:Dataset \([http://www.w3.org/ns/dcat#](http://www.w3.org/ns/dcat#)\). The requester of an asset MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD choose the asset with the highest compatible version number implemented by themselves. +If the requester cannot find a compatible version with their own, the requester MUST terminate the data transfer. + +## 3 ASPECT MODELS + +In this standard, there are no use case specific Aspect Models required. + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is non-normative* + +As the Health Indicator use case is using the Knowledge Agent technology, it provides no onw APIs. Instead, the APIs of the Knowledge Agent are used. Therefore, see CX-0084 Federated Queries in Data Spaces. + +## 5 REFERENCES + +### 5.1 NORMATIVE REFERENCES + +- CX-0018:v3.0 Dataspace Connectivity +- CX-0067:v1.1 Ontology Models to realize federated query in Catena-X (only if using the Knowledge Agent) +- CX-0084:v1.2 Federated Queries in Data Spaces (Knowledge Agent) + +### 5.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0141-HealthIndicatorUseCase/assets/architecture_overview_knowledge_agent.drawio.png b/docs/standards/CX-0141-HealthIndicatorUseCase/assets/architecture_overview_knowledge_agent.drawio.png new file mode 100644 index 000000000..8f0febd6f Binary files /dev/null and b/docs/standards/CX-0141-HealthIndicatorUseCase/assets/architecture_overview_knowledge_agent.drawio.png differ diff --git a/docs/standards/CX-0142-ShopFloorInformationService/CX-0142-ShopFloorInformationService.md b/docs/standards/CX-0142-ShopFloorInformationService/CX-0142-ShopFloorInformationService.md new file mode 100644 index 000000000..75ea0795e --- /dev/null +++ b/docs/standards/CX-0142-ShopFloorInformationService/CX-0142-ShopFloorInformationService.md @@ -0,0 +1,2380 @@ +# CX-0142 Shop Floor Information Service v1.0.0 + +## ABSTRACT + +A Modular Production is part of the value chain. On the one hand, it has to guarantee flexibility and availability, and +on the other, it has to allow for product mixes with small lot sizes. The effects of disturbances and decisions in this +network are not limited to a local area, but also have a major impact on other partners in the value chain network. It +is therefore necessary to exchange values from the shop floor directly with other members of the network, such as +customers or their representatives, like logisticians. This communication is realized with the +Shop-Floor-Information-Service (SIS). This service provides different types of information that a factory can offer to +its customers. It is not dedicated to a specific purpose, as customers may decide how to handle the information +themselves. + +The current version of the standard provides two different kinds of data: Production Forecasting, and Production +Tracking data. To give an example of forecasting data, suppose a customer wants to know when production is expected to +start. He can use the Shop-Floor-Information-Service in order to get the information either directly, via cyclic +messages or via notifications when the calculated production dates change. As an example of production tracking, a +customer can request certain production attributes collected during production, such as the torque of a particular +process step. This data can then be used for both documentation and tracking. + +In order to exchange the data the Shop-Floor-Information-Service defines the necessary data models, such as the +GetProductionForecast data and the ProvideProductionForecast data model as well as GetProductionTracking data and +ProvideProductionTracking data model. This data exchange mechanism between Modular Production and the data consumer is +realized via the Shop-Floor-Information API. + +COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +- *Release 24.05* + - *Merge CX-0068, CX-0069 and CX0075 by combining the different standards that describe the data model, the API and and the process into this combined standard.* + - *Additional functionality added: production tracking aspects.* + - *Update of Production Forecast Models due to update of CX-header.* +- *Release 23.09* + - Initial Release + +## 1 INTRODUCTION + +### 1.1 AUDIENCE & SCOPE + +This standard is relevant for + +- Business Application Providers: their role is to implement the Shop-Floor-Information-Service, +- Data Providers, mainly Modular Productions: they have to provide the data required for the + Shop-Floor-Information-Service, +- Data Consumers, e.g. tier n-1 factories, end customers or logisticians: they have to be able to process the data + provided by the Shop-Floor-Information-Service. + +Stakeholders within Catena-X + +- PURIS, DCM: capacity planning requires a forecast of the products to be delivered, +- OSim: the Forecast Data from the SIS can serve as input for a OSim-simulation, +- Traceability: The production tracking aspect allows recalling production data for a specific product, which can be an asset for traceability. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +Higher-level, external influencing factors from the supply chain, such as delays in the logistics chain for supplier +parts or short-term order changes, may invalidate a production plan that has already been drawn up. Today, such +short-term changes in the general conditions of the production process can often only be taken into consideration +indirectly and made through manual corrections. The solution approaches in the Modular Production use case aim to +increase the flexibility of production in order to better leverage the existing business potential. For this purpose, +services, interface, and data model definitions based on industry standards are offered with the goal of increasing the +flexibility and reliability of industrial production. The shop floor is connected to the Catena-X network using the +Catena-X standardized connectors. Modular Production will offer a Shop-Floor-Information-Service that supplies +information about the production status and planning as needed by other partners in the Catena-X network. The goal is to enable individual production (lot size 1) at the price of series production. In particular, this is to be achieved by automating the orchestration of production resources and planning of production processes as much as possible, thus significantly reducing effort and planning times. A growth in efficiency in the sense of the OEE is achieved by reconfiguring the production in the event of faults to continue operation as well as possible. The increased flexibility creates the space for new business models, such as the interposition of highly prioritized, lucrative orders. As a consequence not only the production is required to be flexible and has to react quickly to changes, it also requires communication of future factory output to the customers. As part of a supply chain the products produced by a Modular Production are part of a bigger product. For this reason, certain parameters are offered to customers by the Production Tracking aspect for the overall documentation of the production process. + +Both partners - a customer and a Modular Production - MUST be members of the Catena X network in order to communicate +with each other. By registering a Modular Production in advance with the Discovery Service, a customer can find it via a +so-called Business Partner Number (BPN). With the help of SSI (Self Sovereign Identity) the correct identity is +guaranteed. + +#### 1.2.1 Forecasting + +The customer uses the *GetProductionForecastData* call in order to request a production forecast, as specified in +section 4.1. The Modular Production generates the required information internally by internal services like a scheduler +and answers accordingly by calling *ProvideProductionForecastData* as specified in section 4.2. For cyclic messages or +notifications, the Customer must unsubscribe from the service when the service is no longer required as described in +Section 4.3. + +![SIS Overview](./assets/SIS_Overview.png) + +The *GetProductionForecastData* as well as the *ProvideProductionForecastData* is using an AAS serialized as a JSON +string which is sent through a connector as defined in \[CX-0018\] (e.g. Tractus-X EDC) mechanism, namely: + +- *GetProductionForecastData* uses "GetProductionForecast" data model and +- *ProvideProductionForecastData* uses "ProvideProductionForecast" data model. + +The unsubscribe call has no corresponding data model, as it is a simple HTTP DELETE. + +The JSON string is standardized in section 3.1-3.3. The standard only describes the sending and receiving of +Shop-Floor-Information-data through a data connector. The object is created and handled by applications of the companies +involved, but these applications are not part of the standard. + +#### 1.2.2 Production Tracking + +The customer uses the *GetProductionTrackingData* call in order to request production tracking information, as specified +in section 4.4. The Modular Production provides the data stored in internal databases and replies accordingly by calling +*ProvideProductionTrackingData* as specified section 4.5. + +![SIS ProductionTracking Overview](./assets/SIS_ProductionTracking_Overview.png) + +The *GetProductionTrackingData* as well as the *ProvideProductionTrackingData* is using an AAS serialized as a JSON +string which is sent through connector defined in \[CX-0018\] (e.g. Tractus-X EDC) mechanisms - namely: + +- *GetProductionTrackingData* uses "*GetProductionTracking*" data model and +- *ProvideProductionTrackingData* uses "*ProvideProductionTracking*" data model. + +The JSON string is standardized in section 3.4-3.5. The standard only describes the sending and receiving of +Shop-Floor-Information-data through a data connector. The object is created and handled by applications of the companies +involved, but these applications are not part of the standard. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +#### 1.3.1 For Production Forecasting + +All participants and their solutions will need to proof, that they conform to Catena-X standards. To validate that the +standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). Any actor using the Production +Forecasting aspect of the Shop-Floor-Information-Service, MUST implement, and follow the following standards: + +- The Shop-Floor-Information-Service Forecasting core business logic – in section 5 +- The Shop-Floor-Information-Service Forecasting standardized API – described section 4 +- The Shop-Floor-Information-Service Forecasting standardized Data Model – described in section 3 + +In order to prove conformity, the participant needs to provide to the conformity assessment body: + +- An example GetProductionForecast-JSON as created by their solution, +- An example ProvideProductionForecast-JSON as created by their solution, +- A proof that their solution can process the example payload JSON as listed below. + +In case an assessee wants to get certified WHEN requesting assessment THEN the assessee produces a letter affirming that +they adhere to this standard and the letter is signed by person who has full power of attorney + +Note that in a future revision of this standard it is planned to offer descriptions of test sets including test cases +and test data for validating API implementations. + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this +specification are non-normative. Everything else in this specification is normative. + +#### 1.3.2 For Production Tracking + +All participants and their solutions will need to proof that they conform to Catena-X standards. To validate that the +standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). Any actor using the +Shop-Floor-Information-Service, MUST implement, and follow the following standards: + +- The Shop-Floor-Information-Service Tracking core business logic – in section 5 +- The Shop-Floor-Information-Service Tracking standardized API – described section 4 +- The Shop-Floor-Information-Service Tracking standardized Data Model – described in section 3 + +In order to prove conformity, the participant needs to provide to the conformity assessment body: + +- An example GetProductionTracking-JSON as created by their solution. +- An example ProvideProductionTracking-JSON as created by their solution. +- A proof that their solution can process the example payload JSON as listed below. + +In case an assessee wants to get certified WHEN requesting assessment THEN the assessee produces a letter affirming that +they adhere to this standard and the letter is signed by person who has full power of attorney + +Note that in a future revision of this standard it is planned to offer descriptions of test sets including test cases +and test data for validating API implementations. + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this +specification are non-normative. Everything else in this specification is normative. + +### 1.4 EXAMPLES + +Disturbances of the supply chain always have a major impact on the following links in the chain. It is therefore +necessary to inform the customers resp. their logistician as soon as possible, as the real date of manufacturing might +vary from the one negotiated in the contract. The Shop-Floor-Information-Service therefore gives an update about the +scheduled production times to allow a better planning for both the tier n-1 customer as well as for the logistic +in-between. + +#### 1.4.1 Production Forecast + +The following sections are providing examples for the API call as well as for the data models corresponding to the +Production Forecast aspects. + +##### 1.4.1.1 API + +Production Forecast provides three API calls. Examples for each call are listed below. + +###### 1.4.1.1.1 Example for GetProductionForecastData + +An example JSON string for GetProductionForecast is discussed in section 1.4.1.2. GetProductionForecastData is the +request to receive Shop-Floor-Information. It contains the BPNS of the requesting partner, the customerID, which is the +internal customerID in the Modular Production management tool and the orderID, for which forecast information is +requested. In addition, the requester can select one of the three communication modes: synchronous (the answer will be +given immediately), cyclic (the information will be given cyclic with a negotiated cycle, e.g., every day etc.) and +notification (changed production date). Each mode requires some additional parameters. + +The execution of the endpoint which is used as the base URL in the asset definition is done via a connector as defined +in \[CX-0018\] (e.g. Tractus-X EDC). As the endpoint execution parameters are sent as path parameters, they are added to +the endpoint call at the data plane of the Tractus-X EDC, which passes them on to the endpoint at the Modular +Production. + +The GetProductionForecastData MUST be sent from the requestor of Shop-Floor-Information to the Modular Production using +an HTTP GET request. + +An example HTTP request is provided below: + +```text +GET /get-production-forecast HTTP/1.1 +Host: localhost: 3000 +Content-Type: application/json +Content-Length: 918 +``` + +```json +{ + "request": { + "orderId": "C95_SLM140_1_W1", + "customerId": "BPNL7588787849VQ", + "deviationOfSchedule": { + "value": 12, + "timeUnit": "unit:secondUnitOfTime" + }, + "productionForecastForAll": false, + "version": "2.0.0", + "notificationInterval": { + "value": 12, + "timeUnit": "unit:secondUnitOfTime" + }, + "communicationMode": "synchronous" + }, + "header": { + "senderBpn": "BPNL6666787765VQ", + "relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy": "2023-06-19T21:24:00+07:00", + "context": "urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0", + "messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn": "BPNL6666787765VQ", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "2.0.0" + } +} +``` + +###### 1.4.1.1.2 Example for ProvideProductionForecastData + +An example JSON string for ProvideProductionForecast is discussed in section 1.4.1.2. ProvideProductionForecastData +returns the current forecast results in synchronous mode. In the case of the cyclic, the notification and the +unsubscribe mode, it contains an immediate confirmation with the corresponding information. In case of a cyclic or +notification event the current forecasting information will be sent using the ProvideProductionForecastData mechanism. +The endpoint, which is used as the base URL in the asset definition, is executed via a connector as defined in +\[CX-0018\] (e.g. Tractus-X EDC). Since the endpoint execution parameters are sent as path parameters, they are added to +the endpoint call at the data plane of the Tractus-X EDC , which forwards them to the endpoint at the producer. + +The ProvideProductionForecastData MUST be sent from the Modular Production to the consumer of the Shop-Floor-Information +using an HTTP POST request. An example HTTP request is provided below: + +```text +POST /provide-production-forecast HTTP/1.1 +Host: localhost:3001 +Content-Type: application/json +Content-Length: 962 +``` + +```json +{ + "productionForecastResponse" : { + "listOfForecastItems" : [ { + "returnCode" : "ok", + "precisionOfForecast" : { + "value" : 12, + "timeUnit" : "unit:secondUnitOfTime" + }, + "reasonsForDelay" : "supplyProblems", + "positionId" : "C95_SLM140_1_W1", + "productionStatus" : "itemReceived", + "productionForecast" : "2023-06-19T21:24:00+07:00", + "forecastDate" : "2023-06-19T21:24:00+07:00" + } ], + "version" : "2.0.0", + "communicationMode" : "synchronous", + "iterationNumber" : 6 + }, + "header" : { + "senderBpn" : "BPNL7588787849VT", + "relatedMessageId" : "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy" : "2023-06-19T21:24:00+07:00", + "context" : "urn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0", + "messageId" : "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn" : "BPNL6666787765VQ", + "sentDateTime" : "2023-06-19T21:24:00+07:00", + "version" : "2.0.0" + } +} +``` + +###### 1.4.1.1.3 Example for Unsubscribe + +Unsubscribe is used to opt out of receiving information in the case of a cyclic or notification request. The endpoint, +which is used as the base URL in the asset definition, is executed via a connector as defined in \[CX-0018\] (e.g. +Tractus-X EDC). Since the endpoint execution parameters are sent as path parameters, they are added to the endpoint call +at the data plane of the Tractus-X EDC, which forwards them to the endpoint at the producer.\ +The Unsubscribe request MUST be sent from the consumer of Shop-Floor-Information to the Modular Production using an HTTP +DELETE request. + +`http://{internal-server}/relatedMessageId/00000000-0000-0000-C000-000000000042` + +The final id value should be copied from the GetProductionForecast. An example HTTP request is seen below: + +```text +DELETE /relatedMessageId/00000000-0000-0000-C000-000000000042 HTTP/1.1 +Host: {{internal-server}} +``` + +##### 1.4.1.2 Data Models + +In this chapter, examples for the data models of the production Forecast are listed, namely GetProductionForecast and +ProvideProductionForecast as well as ShopfloorInformationTypes for common data in form of JSON for reference. + +###### 1.4.1.2.1 GetProductionForecast + +The following dataset shows an example of a GetProductionForecast which will be sent to the GetProductionForecastData +endpoint.\ +Example request in case of synchronous answers: + +```json +{ + "header": { + "senderBpn": "BPNL1234567890SE", + "expectedResponseBy": "2023-07-01T21:24:00+07:00", + "context": "urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0", + "messageId": "00000000-0000-0000-C000-000000000042", + "recipientBpn": "BPNL0987654321RE", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "2.0.0" + }, + "request": { + "precisionOfForecast": { + "timeUnit": "day", + "value": 1 + }, + "offset": { + "timeUnit": "day", + "value": 1 + }, + "orderId": "0007", + "customerId": "BPNL7588787849VQ", + "deviationOfSchedule": { + "timeUnit": "day", + "value": 7 + }, + "productionForecastForAll": false, + "version": "2.0.0", + "notificationInterval": { + "timeUnit": "day", + "value": 2 + }, + "communicationMode": "synchronous" + } +} +``` + +###### 1.4.1.2.2 ProvideProductionForecast + +The following dataset shows an example for a ProvideProductionForecast which will be sent to the +ProvideProductionForecastData endpoint. + +```json +{ + "header": { + "senderBpn": "BPNL1234567890SE", + "relatedMessageId": "00000000-0000-0000-C000-000000000042", + "expectedResponseBy": "2023-07-02T13:00:00.000+02:00", + "context": "urn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0", + "messageId": "00000000-0000-0000-C000-000000000046", + "recipientBpn": "BPNL0987654321RE", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "2.0.0" + }, + "productionForecastResponse": { + "listOfForecastItems": [ + { + "returnCode": "ok", + "precisionOfForecast": { + "timeUnit": "day", + "value": 3 + }, + "reasonsForDelay": "supplyProblems", + "positionId": "0007-3", + "productionStatus": "itemReceived", + "productionForecast": "2023-07-05T14:05:00.000+02:00", + "forecastDate": "2023-07-01T14:05:20.255+02:00" + } + ], + "version": "2.0.0", + "communicationMode": "synchronous", + "iterationNumber": 42 + } +} +``` + +###### 1.4.1.2.3 ShopfloorInformationTypes + +In order to use common data in the different models, ShopfloorInformationTypes have also been defined, an example of +which is shown below:: + +```json +{ + "timeValue": { + "value": 12, + "timeUnit": "unit:secondUnitOfTime" + }, + "communicationMode": "synchronous" +} +``` + +#### 1.4.2 Production Tracking + +In the following sections examples for the API calls and the data models for production tracking are given. + +##### 1.4.2.1 API + +Production Tracking provides two API calls. Examples for each call are listed below. + +###### 1.4.2.1.1 GetProductionTrackingData + +An example JSON string for the GetProductionForecastData can be found in section 1.4.2.2. GetProductionTracking is the +request to obtain Shop-Floor-Information regarding the manufacturing steps of a product. The Model itself contains the +Catena-X Header Aspect +Model (https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.shared.message_header/2.0.0), so +that the BPNS of the requesting partner is provided. Within the request, the customerID, which is the internal +customerID in the Modular Production management tool, and the identifierNumber, which is used to identify the product +for which the production tracking data is requested, are required. + +The execution of the endpoint which is used as the base URL in the asset definition is done via a connector as defined +in \[CX-0018\] (e.g. Tractus-X EDC). As the endpoint execution parameters are sent as path parameters, they are added to +the endpoint call at the data plane of the Tractus-X EDC, which passes them on to the Modular Production Tractus-X +endpoint. + +The GetProductionForecastTracking MUST be sent from the requester of Shop-Floor-Information to the Modular Production +using an HTTP GET request. + +An example of the HTTP request is listed below: + +```text +GET /get-production-tracking HTTP/1.1 +Host: localhost:3000 +Content-Type: application/json +Content-Length: 1007 +``` + +```json +{ + "request" : { + "identifierNumber" : "box-12345678", + "stepIdentifierList" : [ { + "processStepId" : "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01", + "processParameterList" : [ { + "processParameterSemanticId" : "0173-1#02-ABK233#001", + "processParameterName" : "Drehmoment_Max" + } ] + } ], + "customerId" : "550e8400-e29b-41d4-a716-446655440000", + "identifierType" : "partInstanceId", + "billOfProcessId" : "box-with-lid-12345678-bill-of-process", + "version" : "1.0.0", + "processReferenceType" : "processStep" + }, + "header" : { + "senderBpn" : "BPNL7588787849VQ", + "relatedMessageId" : "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy" : "2023-06-19T21:24:00+07:00", + "context" : "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0", + "messageId" : "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn" : "BPNL6666787765VQ", + "sentDateTime" : "2023-06-19T21:24:00+07:00", + "version" : "2.0.0" + } +} +``` + +###### 1.4.2.1.2 ProvideProductionTrackingData + +An example JSON string for the ProvideProductionTracking can be found in section 1.4.2.2. ProvideProductionTrackingData +will return a set of manufacturing steps of a product, whereas each of these steps can feature one or multiple process +parameters, that were specified with the GetProductionForecastData request. These process step information will be +returned so that the requester will receive a single message, containing the ProvideProductionTracking information. + +The execution of the endpoint which is used as the base URL in the asset definition is done via a connector as defined +in \[CX-0018\] (e.g. Tractus-X EDC). As the endpoint execution parameters are sent as path parameters, they are added to +the endpoint call at the data plane of the Tractus-X EDC , which passes them on to the producer's endpoint. + +The ProvideProductionTrackingData MUST be sent from the Modular Production to the consumer of the Shop-Floor-Information +using an HTTP POST request. An example HTTP request is provided below: + +```text +POST /provide-production-tracking HTTP/1.1 +Host: localhost:3001 +Content-Type: application/json +Content-Length: 1015 +``` + +```json +{ + "header": { + "senderBpn": "BPNL7588787849VQ", + "relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy": "2023-06-19T21:24:00+07:00", + "context": "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0", + "messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn": "BPNL6666787765VQ", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "2.0.0" + }, + "response": { + "identifierNumber": "box-12345678", + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "identifierType": "partInstanceId", + "version": "1.0.0", + "processStepIdentifierList": [ + { + "processStepId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01", + "processParameterValueList": [ + { + "processParameterName": "Drehmoment_Max", + "semanticId": "0173-1#02-ABK233#001", + "processParameterQuality": "ok", + "processParameterValue": "10" + } + ] + } + ] + } +} +``` + +##### 1.4.2.2 Data Models + +This chapter provides examples of the production tracking data models, namely GetProductionTracking and +ProvideProductionTracking, for common data in form of JSON for reference. + +###### 1.4.2.2.1 GetProductionTracking + +The GetProductionTracking data model contains three different cases for a request, namely a partInstanceId, a billOfMaterialId and +a billOfProcessId based request, which will be sent to the endpoint GetProductionTrackingData. The cases differ in the various +optional fields that become mandatory for the individual cases. The following example illustrates the overall model, +however, detailed examples for each of the aforementioned cases are provided in sections 1.4.2.2.1.1 through +1.4.2.2.1.3. In all cases, it is assumed that the required information is common knowledge to both the factory and the +customer requesting GetProductionTracking. + +```json +{ + "request": { + "identifierNumber": "box-12345678", + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "stepIdentifierList": [ + { + "processStepId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01", + "processParameterList": [ + { + "processParameterSemanticId": "0173-1#02-ABK233#001", + "processParameterName": "Drehmoment_Max" + } + ], + "capabilityId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben", + "billOfMaterialElementId": "Deckel-Bom-123-Schraube", + "partInstanceLevel": "partInstanceId", + "partInstanceId": "Deckel-Serial-123", + "billOfMaterialId": "321-BomIdentifier" + } + ], + "customerId": "550e8400-e29b-41d4-a716-446655440000", + "billOfProcessId": "box-with-lid-12345678-bill-of-process", + "identifierType": "partInstanceId", + "version": "1.0.0", + "processReferenceType": "processStep" + }, + "header": { + "senderBpn": "BPNL7588787849VQ", + "relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy": "2023-06-19T21:24:00+07:00", + "context": "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0", + "messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn": "BPNL6666787765VQ", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "2.0.0" + } +} +``` + +###### 1.4.2.2.1.1 PartInstanceId based Request + +The following shows an example of a partInstanceId based request, where the product and the requested process steps are +identified based on on a partInstanceId and a performed capability: + +```json +{ + "request": { + "identifierNumber": "box-12345678", + "stepIdentifierList": [ + { + "processParameterList": [ + { + "processParameterSemanticId": "0173-1#02-ABK233#001", + "processParameterName": "Drehmoment_Max" + } + ], + "capabilityId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben", + "partInstanceLevel": "partInstanceId", + "partInstanceId": "Deckel-Serial-123" + } + ], + "customerId": "550e8400-e29b-41d4-a716-446655440000", + "identifierType": "partInstanceId", + "version": "1.0.0", + "processReferenceType": "capability" + }, + "header": { + "senderBpn": "BPNL7588787849VQ", + "relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy": "2023-06-19T21:24:00+07:00", + "context": "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0", + "messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn": "BPNL6666787765VQ", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "2.0.0" + } +} +``` + +###### 1.4.2.2.1.2 billOfMaterialId based Request + +The following shows an example of the billOfMaterialId based request, where the product and the requested process steps are +identified based on on a billOfMaterialId and a performed capability: + +```json +{ + "request": { + "identifierNumber": "box-12345678", + "stepIdentifierList": [ + { + "processStepId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01", + "processParameterList": [ + { + "processParameterSemanticId": "0173-1#02-ABK233#001", + "processParameterName": "Drehmoment_Max" + } + ], + "capabilityId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben", + "billOfMaterialElementId": "Deckel-Bom-123-Schraube", + "partInstanceLevel": "bomId", + "billOfMaterialId": "321-BomIdentifier" + } + ], + "customerId": "550e8400-e29b-41d4-a716-446655440000", + "identifierType": "bomId", + "version": "1.0.0", + "processReferenceType": "capability" + }, + "header": { + "senderBpn": "BPNL7588787849VQ", + "relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy": "2023-06-19T21:24:00+07:00", + "context": "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0", + "messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn": "BPNL6666787765VQ", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "2.0.0" + } +} +``` + +###### 1.4.2.2.1.3 billOfProcessId based Request + +The following shows an example of the billOfProcessId based request, where the product can be identified based on a batchId, a +partInstanceId or a billOfMaterialId. However, instead of a capability, the process step is identified based on a commonly defined +bill of process: + +```json +{ + "request": { + "identifierNumber": "box-12345678", + "stepIdentifierList": [ + { + "processStepId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01", + "processParameterList": [ + { + "processParameterSemanticId": "0173-1#02-ABK233#001", + "processParameterName": "Drehmoment_Max" + } + ] + } + ], + "customerId": "550e8400-e29b-41d4-a716-446655440000", + "identifierType": "partInstanceId", + "billOfProcessId": "box-with-lid-12345678-bill-of-process", + "version": "1.0.0", + "processReferenceType": "processStep" + }, + "header": { + "senderBpn": "BPNL7588787849VQ", + "relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy": "2023-06-19T21:24:00+07:00", + "context": "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0", + "messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn": "BPNL6666787765VQ", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "2.0.0" + } +} +``` + +###### 1.4.2.2.2 ProvideProductionTracking + +The following dataset shows an example for a ProvideProductionTracking which will be sent to the +ProvideProductionTrackingData endpoint. Regardless of the case of the request, the response information is always the +same. + +```json +{ + "header": { + "senderBpn": "BPNL7588787849VQ", + "relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy": "2023-06-19T21:24:00+07:00", + "context": "urn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0", + "messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn": "BPNL6666787765VQ", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "2.0.0" + }, + "response": { + "identifierNumber": "box-12345678", + "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "identifierType": "partInstanceId", + "version": "1.0.0", + "processStepIdentifierList": [ + { + "processStepId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01", + "processParameterValueList": [ + { + "processParameterName": "Drehmoment_Max", + "semanticId": "0173-1#02-ABK233#001", + "processParameterQuality": "ok", + "processParameterValue": "10" + } + ] + } + ] + } +} +``` + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +| Name | Abbreviation | Description | +| ----- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| AAS | Asset Administration Shell | Specification to manage and administrate digital representations of assets (concepts, physical device, process, etc.). Used synonymously with the term "Digital Twin". | +| AM | Aspect Model | a formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect.Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model.Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). | +| BPN | Business Partner Number | Business Partner Number | +| CX | Catena-X | Data ecosystem / data space for the automotive industry. | +| DCM | Demand and Capacity Management | Product within Catena-X for shortage identification. | +| DT | Digital Twin | Digital representation of an asset (concept, physical device, process, etc.). Realized using the Asset Administration Shell. Used synonymously with the term "Asset Administration Shell". | +| EDC | Eclipse Dataspace Connector | Open-Source Dataspace Connector Framework to participate in International Data Spaces. | +| JSON | JavaScript Object Notation | Json is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects. | +| MP | Modular Production | Product within Catena-X for shop floor activities | +| OSim | Online Control and Simulation | Product within Catena-X for Online Simulation along the supply chain | +| PURIS | Predictive Unit Real-Time Information System | Product within Catena-X for shortage identification. | +| SAMM | Semantic aspect meta model | Modelling specification to realize a standardized set of models with strict typing which can be used within the AAS. SAMMs are standardized via the Semantic Layer team and can be looked up via the Semantic Hub. | +| SIS | Shop-Floor-Information-Service | Service provided by MP in order to give information from the shop floor to customers and third parties | +| SSI | Self Sovereign Identity | Self Sovereign Identity | + +```text + Additional terminology used in this standard can be looked up in the glossary on the association homepage. +``` + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 "Modular Production" + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +- *CX-0001 EDC Discovery API* Version 1.0.2 +- *CX-0003 SAMM Aspect Meta Model Version 1.1.0 or 1.0.2* +- *CX-0018 **Dataspace Connectivity** Version 3.0.0* + +#### 2.1.2 DATA REQUIRED + +No additional data requirements. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +**Conventions for Use Case Policy in context data exchange**: + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the +Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the +conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the +Catena-X ecosystem, we refer users to + +- the + detailed [ODRL policy repository](https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fcatenax-eV%2Fcx-odrl-profile&data=05%7C02%7Cjanchristoph.wehrstedt%40siemens.com%7C05a0c15c764248e9ac8f08dc3452af45%7C38ae3bcd95794fd4addab42e1495d55a%7C1%7C0%7C638442776973800689%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=x%2BNCiEm%2Fxhq3qHcIQ%2FDcxhtCzL8Yc5YBowyW9et8BnM%3D&reserved=0). + This document provides in-depth explanations of the terms and conditions applied to data access and utilization, + ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas MUST + be followed when providing services or apps for data sharing/consuming. + +**Additional Details regarding Access Policies**: + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and +one or several Data Consumers. By limiting access to certain participants, the Data Provider maintains control over its +anti-trust obligations when sharing certain data. In particular, the Data Provider may apply Access Policies to restrict +access to a particular data offer for only one participant identified by a specific business partner number. + +**Additional Details regarding Usage Policies**: + +In the context of data usage policies (“Usage Policies”), Participants and related services MUST use the following +policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above + mentioned [ODRL policy repository](https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fcatenax-eV%2Fcx-odrl-profile&data=05%7C02%7Cjanchristoph.wehrstedt%40siemens.com%7C05a0c15c764248e9ac8f08dc3452af45%7C38ae3bcd95794fd4addab42e1495d55a%7C1%7C0%7C638442776973818516%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=0BdTHllOvpwpx5IoCUIhTBBJlcTX%2FfSEvzPJQv9ZNJ0%3D&reserved=0). + +Additionally, respective usage policies MAY include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODLR policy rule values to be used for the above-mentioned types are provided via +the [ODRL policy repository](https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fcatenax-eV%2Fcx-odrl-profile&data=05%7C02%7Cjanchristoph.wehrstedt%40siemens.com%7C05a0c15c764248e9ac8f08dc3452af45%7C38ae3bcd95794fd4addab42e1495d55a%7C1%7C0%7C638442776973830220%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=Ni%2BHYAEEV9rkmbf3AVNM2NNQoKmbngTjrvtPObf2w1A%3D&reserved=0). + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +This version of the document does not define any requirements for standardized integration and governance of digital +twins. + +## 3 ASPECT MODELS + +> *This section is normative* + +### 3.1 ASPECT MODEL "GetProductionForecast" + +#### 3.1.1 INTRODUCTION + +The GetProductionForecast MUST be sent by the customer or a third party to the Modular Production via an HTTP request. +The data format described here MUST be followed. The GetProductionForecast data model MUST be implemented by all +participants who wish to use the Shop-Floor-Information-Service as a Modular Production, a customer or a participating +third party. For GetProductionForecast the requester MUST either select the "synchronous", "cyclic" or "notification" +communication mode. Companies which use the Shop-Floor-Information-Service as a customer or third party MUST be able to +send GetProductionForecastData requests. Companies which use the Shop-Floor-Information-Service as a Modular Production +MUST be able to receive GetProductionForecastData requests. + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" +to create a submodel template specification [SMT](#62-non-normative-references). + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 as input for the semantic driven +workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003. + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International ( +CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text + urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0 +``` + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The RDF turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats +and serializations. + +> https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shopfloor_information.get_production_forecast/2.0.0/GetProductionForecast.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file +formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset +Administration Shell for the API operation "GetSubmodel". + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a +Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)\]. + +##### 3.1.5.4 SEMANTIC MODEL + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International ( +CC-BY-4.0) license, which is available at Creative Commons. + +The GetProductionForecast model is described in detail in the table below: + +| Field | Level | REQUIRED | Purpose | Data Type | Example Value | +| ---------------------- | ----------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------- | +| senderBpn | CX-header | mandatory | identification of the sender | string | BPNL1234567890SE | +| recipientBpn | CX-header | mandatory | identification of the recipient | string | BPNL0987654321RE | +| expectedResponseBy | CX-header | mandatory | Deadline for the first response | date | 2023-07-01T21:24:00+07:00 | +| messageId | CX-header | mandatory | unique ID for message will be used as requestID for the following communication | UUID | 00000000-0000-0000-C000-000000000046 | +| context | CX-header | mandatory | Information about the context the message should be considered in, e.g. "MP-Request" | string | MUST BE urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0 | +| sentDateTime | CX-header | mandatory | time of request | string | 2023-06-19T21:24:00+07:00 | +| version | CX-header | mandatory | of Meta model used for compatibility | string | 2.0.0 | +| relatedMessageId | CX-header | optional | not used for request; will be used in the following parts to refer to the request | UUID | 00000000-0000-0000-C000-000000000042 | +| version | SIS-Payload | mandatory | version of the datamodel | string | 2.0.0 | +| customerId | SIS-Payload | mandatory | The internal ID of the customer of the Modular Production in order to identify the customer in the database | string | VLhpfQGTMDYpsBZxvfBoeygjb | +| orderId | SIS-Payload | mandatory | The orderID communicated between the Modular Production and the customer | string | 0007 | +| communicationMode | SIS-Payload | mandatory | Enum describing which communication mode is used for data exchange resp. the mode of the response: synchronous, cyclic or notification | enum | synchronous | +| productionForecast4All | SIS-Payload | mandatory | if true, the forecast for the entire order will be sent (more precise: latest production date of all suborders ) instead of splitting it in the suborders | bool | true | +| offset | SIS-Payload | mandatory | timespan to activating of cyclic and notification; for immediate response it should be "0" | TimeValue \[EnumTimeUnits, uint \] | \{"timeUnit": "day", "value": 1 \} | +| notificationInterval | SIS-Payload | optional if \[cyclic\] = mandatory | in case of cyclic notification it is giving the period of the notification cycles if (communicationMode == \[cyclic\]) => mandatory | TimeValue \[EnumTimeUnits, uint \] | \{"timeUnit": "day", "value": 2 \} | +| deviationOfSchedule | SIS-Payload | optional if \[notification\] = mandatory | in case of notification a tolerance will be defined for triggering a new notification to avoid too many notifications with smaa deviations in the forecasting date if (communicationMode == \[notification\]) => mandatory | TimeValue \[EnumTimeUnits, uint \] | \{"timeUnit": "day", "value": 7 \} | +| precisionOfForecast | SIS-Payload | optional | Requested precision of the forecasting date default, the production defines the date in case of a requested precisionOfForecast, the Modular Production delivers with the required precision if the precision is not possible, an error code is send and the forecast will be the best possible precision | TimeValue \[EnumTimeUnits, uint \] | \{"timeUnit": "day", "value": 1 \} | + +- The context field in the header MUST be urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0. +- The API GetProductionForecastData 4.1 call MUST use the GetProductionForecast data model. +- Communication Mode MUST be one of the following items: synchronous, cyclic and notification. +- EnumTimeUnits MUST be one of the following items: seconds, minutes, hour, day, week, month, year. + +### 3.2 ASPECT MODEL "ProvideProductionForecast" + +#### 3.2.1 INTRODUCTION + +Companies which use the Shop-Floor-Information-Service as a customer or third party MUST be able to receive +ProvideProductionForecast information. Companies which use the Shop-Floor-Information-Service as a factory MUST be able +to send ProvideProductionForecast information. + +#### 3.2.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" +to create a submodel template specification SMT. + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 as input for the semantic driven +workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003. + +#### 3.2.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International ( +CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.2.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0 +``` + +#### 3.2.5 FORMATS OF SEMANTIC MODEL + +##### 3.2.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats +and serializations. + +> https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shopfloor_information.provide_production_forecast/2.0.0/ProvideProductionForecast.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file +formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.2.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset +Administration Shell for the API operation "GetSubmodel". + +##### 3.2.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a +Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)\]. + +##### 3.2.5.4 SEMANTIC MODEL + +The ProvideProductionForecastData model is described in detail in the following table: + +| Field | Level | REQUIRED | Purpose | Datatype | Example Value | +| ------------------- | ----------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------- | +| version | CX-header | mandatory | of Meta model used for compatibility | string | 2.0.0 | +| messageId | CX-header | mandatory | unique ID for message will be used as requestID for the following communication | UUID | 00000000-0000-0000-C000-000000000046 | +| context | CX-header | mandatory | Information about the context the message should be considered in, e.g. "MP-Request" | string | MUST BEurn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0 | +| sentDateTime | CX-header | mandatory | time of request | string | 2023-06-19T21:24:00+07:00 | +| senderBpn | CX-header | mandatory | identification of the sender | string | BPNL1234567890SE | +| recipientBpn | CX-header | mandatory | identification of the recipient | string | BPNL0987654321RE | +| expectedResponseBy | CX-header | mandatory | Deadline for the first response | date | 2023-07-02T13:00:00.000+02:00 | +| relatedMessageId | CX-header | optional | not used for request; will be used in the following parts to refer to the request | UUID | 00000000-0000-0000-C000-000000000042 | +| version | SIS-Payload | mandatory | version of the datamodel | string | 2.0.0 | +| iterationNo | SIS-Payload | optional | in case of cyclic or notification mode this field is used to count the iterations to keep them in the correct order | int | 42 | +| communicationMode | SIS-Payload | mandatory | Enum describing if synchronous, cyclic or notification is used for data exchange | enum | synchronous | +| ListOfForecastItems | SIS-Payload | mandatory | list containing the items corresponding to the order of this request | List of Forecast Items | | +| ForecastItem\* | SIS-Payload | | | | | +| positionId | SIS-Payload | mandatory | field referring to the ID of this item in the order list, e.g. item number in case of productionForecastForAll =true : provide order ID instead of position ID | UUID / string | 0007-3 | +| productionForecast | SIS-Payload | mandatory | date of finalizing the production, this does not cover additional internal activities e.g. logistic | datetime | 2023-07-05T14:05:00.000+02:00 | +| precisionOfForecast | SIS-Payload | mandatory | precision of the forecast in form of an interval e.g. +-3days, the precision either matches to the required precision of the request or the maximal possible precision. | TimeValue \[EnumTimeUnits, uint \] | \{ "timeUnit": "day", "value": 3 \}, | +| productionStatus | SIS-Payload | mandatory/opt | status of the production | enum \ | itemReceived | +| forecastDate | SIS-Payload | mandatory | date of determination the forecasting status | datetime | 2023-07-01T14:05:20.255+02:00 | +| reasonForDelay | SIS-Payload | mandatory | in case of a delay a possible explanation | enum | supplyProblems | + +- The context field in the header MUST be urn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0. +- The API ProvideProductionForecastData call in section 4.2 MUST use the ProvideProductionForecast data model. +- Communication Mode MUST be one of the following items: synchronous, cyclic and notification. +- EnumTimeUnits MUST be one of the following items: unit:secondUnitOfTime, unit:minuteUnitOfTime, unit:hour, unit:day, + unit:week, unit:month, unit:year. +- ProductionStatus MUST be one of the following items: itemReceived, itemPlanned, itemInProduction, itemCompleted, + statusUndefined, ordered following the figure below. + +![Production States](./assets/ProductionStates.png) + +- reasonsForDelay MUST be one of the following items: supplyProblems, internalProblems, otherCircumstances, + noInformationAvailable. + +### 3.3 ASPECT MODEL "ShopfloorInformationTypes " + +The ShopfloorInformationTypes MUST be used for all parties using ProvideProductionForecastData or +GetProductionForecastData information. + +#### 3.3.1 INTRODUCTION + +The ShopfloorInformationTypes are a collection of commonly used data models of ProvideProductionForecastData or +GetProductionForecastData. + +#### 3.3.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" +to create a submodel template specification SMT. + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 as input for the semantic driven +workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003. + +#### 3.3.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International ( +CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.3.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier: + +```text + urn:samm:io.catenax.shared.shopfloor_information_types:2.0.0 +``` + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +#### 3.3.5 FORMATS OF SEMANTIC MODEL + +##### 3.3.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats +and serializations. + +> https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shared.shopfloor_information_types/2.0.0/ShopfloorInformationTypes.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file +formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.3.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset +Administration Shell for the API operation "GetSubmodel". + +##### 3.3.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a +Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)\]. + +##### 3.3.5.4 SEMANTIC MODEL + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International ( +CC-BY-4.0) license, which is available at Creative Commons. + +The ShopfloorInformationTypes model is described in detail in the following table: + +| Field | Purpose | Datatype | Example Value | +| ----------------- | -------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------- | +| communicationMode | Enum describing if synchronous, cyclic or notification is used for data exchange | enum | synchronous | +| timeValue | dataFormat for storing timeValues | TimeValue \[EnumTimeUnits, uint \] | \{ "timeUnit": "day", "value": 3 \} | + +Communication Mode MUST be one of the following items: synchronous, cyclic and notification. + +EnumTimeUnits MUST be one of the following items: unit:secondUnitOfTime, unit:minuteUnitOfTime, unit:hour, unit:day, +unit:week, unit:month, unit:year. + +### 3.4 ASPECT MODEL "GetProductionTracking" + +The GetProductionTracking data model MUST be used for all parties using GetProductionTrackingData. + +#### 3.4.1 INTRODUCTION + +#### 3.4.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" +to create a submodel template specification SMT. + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 as input for the semantic driven +workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003. + +#### 3.4.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International ( +CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.4.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text +urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0 +``` + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +#### 3.4.5 FORMATS OF SEMANTIC MODEL + +##### 3.4.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats +and serializations. + +> https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shopfloor_information.get_production_tracking/1.0.0/GetProductionTracking.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file +formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.4.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset +Administration Shell for the API operation "GetSubmodel". + +##### 3.4.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a +Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)\]. + +#### 3.4.5.4 SEMANTIC MODEL + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International ( +CC-BY-4.0) license, which is available at Creative Commons. + +The GetProductionTracking model is described in detail in the following table: + +| Field | Level | Required | Purpose | Datatype | Example Value | +| -------------------------- | ----------- | --------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------ | +| header | | | | | | +| senderBpn | CX-Header | mandatory | of Meta Model used for compatibility | BpnlCharacteristic | BPNL1234567890SE | +| version | CX-header | mandatory | of Meta model used for compatibility | VersionCharacteristic | 2.0.0 | +| messageId | CX-header | mandatory | unique ID for message will be used as requestID for the following communication | UUID | 00000000-0000-0000-C000-000000000046 | +| context | CX-header | mandatory | Information about the context the message should be considered in, e.g. "MP-Request" | string | MUST BE urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0 | +| sentDateTime | CX-header | mandatory | time of request | string | 2023-06-19T21:24:00+07:00 | +| recipientBpn | CX-header | mandatory | identification of the recipient | BpnlCharacteristic | BPNL0987654321RE | +| expectedResponseBy | CX-header | mandatory | Deadline for the first response | date | 2023-07-02T13:00:00.000+02:00 | +| relatedMessageId | CX-header | optional | not used for request; will be used in the following parts to refer to the request | UUID | 00000000-0000-0000-C000-000000000042 | +| request | | | | | | +| version | SIS-Payload | mandatory | of Meta model used for compatibility | VersionCharacteristic | 1.0.0 | +| customerId | SIS-Payload | mandatory | internal customer number | string | 550e8400-e29b-41d4-a716-446655440000 | +| catenaXId | SIS-Payload | optional | identifier of a product that is registered in a catena-x digital twin registry | uuid | urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379 | +| identifierType | SIS-Payload | mandatory | specifies the kind of the identifierNumber | enum : [partInstanceId, batchId, billOfMaterialId] | partInstanceId | +| identifierNumber | SIS-Payload | mandatory | identifier of a product | string | box-12345678 | +| processReferenceType | SIS-Payload | mandatory | determines whether a process step is identified with a capability or a processStepIdentifier of a billOfProcess | string | processStep | +| billOfProcessId | SIS-Payload | optional | identifier of a bill of process known by both partners | string | box-with-lid-12345678-bill-of-process | +| stepIdentifierList | SIS-Payload | mandatory | lists all process steps from which parameters are requested | list | | +| capabilityId | SIS-Payload | optional | identifier of a capability | string | Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben | +| partInstanceLevel | SIS-Payload | optional | determines whether a sub-product is identified based on a bill of material or a partInstanceId | enum : [partInstanceId, billOfMaterialId] | partInstanceId | +| billOfMaterialId | SIS-Payload | optional | identifier of a bill of material | string | 321-BomIdentifier | +| billOfMaterialElementId | SIS-Payload | optional | identifies a concrete element of the bill of material referenced with the billOfMaterialId | string | Deckel-Bom-123-Schraube | +| partInstanceId | SIS-Payload | optional | partInstanceId to identify a sub-product of a product | string | Deckel-Serial-123 | +| processStepId | SIS-Payload | optional | identifier of a process step referenced in the billOfProcessId | string | Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01 | +| processParameterList | SIS-Payload | mandatory | Lists all process Parameter requested from a process step | list | | +| processParameterName | SIS-Payload | mandatory | name of a requested process parameter | string | Drehmoment_Max | +| processParameterSemanticId | SIS-Payload | mandatory | link to a semantic that characterizes the type of the process parameter | string | 0173-1#02-ABK233#001 | + +- The context field in the header MUST be urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0. +- IdentifierType MUST be one of the following items: partInstanceId, batchId, billOfMaterialId +- processReferenceType Mode MUST be one of the following items: processStep, capability +- partInstanceLevel MUST be one of the following items: partInstanceId, billOfMaterialId +- partInstanceId COULD be a serial number or a different unique identifier for a specific part of an asset + +### 3.5 ASPECT MODEL "ProvideProductionTracking" + +The ProvideProductionTracking data model MUST be used for all parties using ProvideProductionForecastData. + +#### 3.5.1 INTRODUCTION + +The ProvideProductionTracking are a collection of commonly used data models of ProvideProductionTrackingData. + +#### 3.5.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" +to create a submodel template specification SMT. + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to CX-0003 as input for the semantic driven +workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to CX-0003. + +#### 3.5.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International ( +CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.5.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +```text +urn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0 +``` + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +#### 3.5.5 FORMATS OF SEMANTIC MODEL + +##### 3.5.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats +and serializations. + +> https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shopfloor_information.provide_production_tracking/1.0.0/ProvideProductionTracking.ttl + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file +formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +##### 3.5.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset +Administration Shell for the API operation "GetSubmodel". + +##### 3.5.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a +Submodel Template Specification conformant to \[[SMT](#62-non-normative-references)\]. + +##### 3.5.5.4 SEMANTIC MODEL + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International ( +CC-BY-4.0) license, which is available at Creative Commons. + +The ProvideProductionTracking data model is described in detail in the following table: + +| Field | Level | Required | Purpose | Datatype | Example Value | +| -------------------------- | ----------- | --------- | ------------------------------------------------------------------------------------ | --------------------- | ---------------------------------------------------------------------------------- | +| header | | | | | | +| senderBpn | CX-Header | mandatory | of Meta Model used for compatibility | BpnlCharacteristic | BPNL1234567890SE | +| version | CX-header | mandatory | of Meta model used for compatibility | VersionCharacteristic | 2.0.0 | +| messageId | CX-header | mandatory | unique ID for message will be used as requestID for the following communication | UUID | 00000000-0000-0000-C000-000000000046 | +| context | CX-header | mandatory | Information about the context the message should be considered in, e.g. "MP-Request" | string | MUST BEurn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0 | +| sentDateTime | CX-header | mandatory | time of request | string | 2023-06-19T21:24:00+07:00 | +| recipientBpn | CX-header | mandatory | identification of the recipient | BpnlCharacteristic | BPNL0987654321RE | +| expectedResponseBy | CX-header | mandatory | Deadline for the first response | date | 2023-07-02T13:00:00.000+02:00 | +| relatedMessageId | CX-header | optional | not used for request; will be used in the following parts to refer to the request | UUID | 00000000-0000-0000-C000-000000000042 | +| response | | | | | | +| version | SIS-Payload | mandatory | of Meta model used for compatibility | VersionCharacteristic | 1.0.0 | +| catenaXId | SIS-Payload | optional | identifier of a product that is registered in a catena-x digital twin registry | uuid | urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379 | +| identifierType | SIS-Payload | mandatory | specifies the kind of the identifierNumber | enum | partInstanceId | +| identifierNumber | SIS-Payload | mandatory | identifier of a product | string | box-12345678 | +| processStepIdentifierList | SIS-Payload | mandatory | Lists all process steps for which parameters are provided | list | | +| processStepId | SIS-Payload | optional | identifier of a process step referenced in the billOfProcessId | string | Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01 | +| processParameterValueList | SIS-Payload | mandatory | Lists all process Parameter provided for a process step | list | | +| processParameterName | SIS-Payload | mandatory | name of a requested process parameter | string | Drehmoment_Max | +| processParameterSemanticId | SIS-Payload | mandatory | link to a semantic that characterizes the type of the process parameter | string | 0173-1#02-ABK233#001 | +| processParameterValue | SIS-Payload | mandatory | the concrete value of a process parameter | string | 10 | +| processParameterQuality | SIS-Payload | mandatory | indicates the quality of the parameters value measurement | enum | noValue | + +- The context field in the header MUST be urn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0. +- IdentifierType MUST be one of the following items: partInstanceId, batchId, billOfMaterialId +- processReferenceType Mode MUST be one of the following items: processStep, capability +- partInstanceLevel MUST be one of the following items: partInstanceId, billOfMaterialId + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +### 4.1 "GetProductionForecastData" API + +This introduction holds for 4.1-4.3: + +The GetProductionForecastData contains the request for forecast data sent by a Modular Production partner to a customer +or a third party at the next lower level. All participants using the Shop-Floor-Information-Service in the role of a a +customer or third party MUST be able to send GetProductionForecastData. All participants using the +Shop-Floor-Information-Service in the role of a Modular Production MUST be able to receive and process +GetProductionForecastData. + +The following diagram shows the complete communication between the partners in an abstract way. It takes place in +different phases: + +1. **Negotiation** between the connector as in \[CX-0018\] (e.g. Tractus-X EDC), +1. Data connector of the partners using the needed policies, +1. GetProductionForecastData(...) - the call of the customer, +1. get the desired information via ProvideProductionForecastData(...) - transferred by Modular Production (synchronous, + cyclic or notification-like), +1. Unsubscribe from the "GetProductionForecastData" service to stop receiving further information. + +![Production Tracking](./assets/SIS_ProductionTracking.png) + +The two boxes in the middle represent the data connector like Tractus-X EDC of the partners. The communication between +the respective connectors is transparent to the user (shaded). The transmission of the data for the request, as well as +the response to the ProductionForecast is transmitted via the payload of the message. The immediate response (http +response) does not contain any technical information. The left side represents the customer with his different requests. +On the right is the Modular Production with a scheduler that generates the requested answers. + +#### 4.1.1 PRECONDITIONS AND DEPENDENCIES + +The GetProductionForecastData API MUST be published towards the network using a Data Asset/Contract Offer in terms of +the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC). + +#### 4.1.2 API SPECIFICATION + +##### 4.1.2.1 API Endpoints & resources + +When sending a request to the GetProductionForecastDataEndpoint, the body MUST be composed out of two information +objects: a *header* and *content*. Together they form the HTTP body that MUST be formatted as JSON. + +The elements of the message are described in the following table: + +| Field | Level | REQUIRED | Purpose | Data Type | Example Value | +| ---------------------- | ----------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------- | +| senderBpn | CX-header | mandatory | identification of the sender | string | BPNL1234567890SE | +| recipientBpn | CX-header | mandatory | identification of the recipient | string | BPNL0987654321RE | +| expectedResponseBy | CX-header | mandatory | Deadline for the first response | date | 2023-07-01T21:24:00+07:00 | +| messageId | CX-header | mandatory | unique ID for message will be used as requestID for the following communication | UUID | 00000000-0000-0000-C000-000000000046 | +| context | CX-header | mandatory | Information about the context the message should be considered in, e.g. "MP-Request" | string | MUST BE urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0 | +| sentDateTime | CX-header | mandatory | time of request | string | 2023-06-19T21:24:00+07:00 | +| version | CX-header | mandatory | of Meta model used for compatibility | string | 2.0.0 | +| relatedMessageId | CX-header | optional | not used for request; will be used in the following parts to refer to the request | UUID | 00000000-0000-0000-C000-000000000042 | +| version | SIS-Payload | mandatory | version of the datamodel | string | 2.0.0 | +| customerId | SIS-Payload | mandatory | The internal ID of the customer of the Modular Production in order to identify the customer in the database | string | VLhpfQGTMDYpsBZxvfBoeygjb | +| orderId | SIS-Payload | mandatory | The orderID communicated between the Modular Production and the customer | string | 0007 | +| communicationMode | SIS-Payload | mandatory | Enum describing which communication mode is used for data exchange resp. the mode of the response: synchronous, cyclic or notification | enum | synchronous | +| productionForecast4All | SIS-Payload | mandatory | if true, the forecast for the entire order will be sent (more precise: latest production date of all suborders ) instead of splitting it in the suborders | bool | true | +| offset | SIS-Payload | mandatory | timespan to activating of cyclic and notification; for immediate response it should be "0" | TimeValue \[EnumTimeUnits, uint \] | \{ "timeUnit": "day", "value": 1 \} | +| notificationInterval | SIS-Payload | optional if \[cyclic\] = mandatory | in case of cyclic notification it is giving the period of the notification cycles if (communicationMode == \[cyclic\]) => mandatory | TimeValue \[EnumTimeUnits, uint \] | \{"timeUnit": "day", "value": 2 \} | +| deviationOfSchedule | SIS-Payload | optional if \[notification\] = mandatory | in case of notification a tolerance will be defined for triggering a new notification to avoid too many notifications with smaa deviations in the forecasting date if (communicationMode == \[notification\]) => mandatory | TimeValue \[EnumTimeUnits, uint \] | \{ "timeUnit": "day", "value": 7 \} | +| precisionOfForecast | SIS-Payload | optional | Requested precision of the forecasting date default, the production defines the date in case of a requested precisionOfForecast, the Modular Production delivers with the required precision if the precision is not possible, an error code is send and the forecast will be the best possible precision | TimeValue \[EnumTimeUnits, uint \] | \{"timeUnit": "day", "value": 1 \} | + +The following JSON object gives an example of a valid data model: + +```json +{ + "header": { + "senderBpn": "BPNL1234567890SE", + "expectedResponseBy": "2023-07-01T21:24:00+07:00", + "context": "urn:samm:io.catenax.shopfloor_information.get_production_forecast:2.0.0", + "messageId": "00000000-0000-0000-C000-000000000046", + "recipientBpn": "BPNL0987654321RE", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "2.0.0" + }, + "request": { + "precisionOfForecast": { + "timeUnit": "day", + "value": 1 + }, + "offset": { + "timeUnit": "day", + "value": 1 + }, + "orderId": "0007", + "customerId": "BPNL7588787849VQ", + "deviationOfSchedule": { + "timeUnit": "day", + "value": 7 + }, + "productionForecastForAll": false, + "version": "2.0.0", + "notificationInterval": { + "timeUnit": "day", + "value": 2 + }, + "communicationMode": "synchronous" + } +} +``` + +**Available Data Types**: + +- The API GetProductionForecastData call MUST use the GetProductionForecast data model defined in section 3.1. +- The API MUST use JSON as the payload transported via HTTPS. More information on the data objects supported by the + endpoints is provided in the corresponding sections of Section 3.1. +- Communication Mode MUST be one of the following items: synchronous, cyclic and notification. +- EnumTimeUnits MUST be one of the following items: unit:secondUnitOfTime, unit:minuteUnitOfTime, unit:hour, unit:day, + unit:week, unit:month, unit:year. + +#### 4.1.2.2 DATA ASSET STRUCTURE + +The HTTP GET endpoint introduced in chapter 4.1.1 MUST NOT be called from a partner directly. Rather, it MUST be called +via the communication defined in \[CX-0018\]. Therefore, the endpoint MUST be offered as an Data Asset. + +- The latter MUST have a property “asset.properties.asset:prop:id”. This property MUST be used to identify the asset + when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects + the contractual relationship between Shop-Floor-Information-Service partners, only one asset with the aforementioned + property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen + freely but must be unique. +- The asset definition SHOULD contain a property “asset.properties.asset:prop.description” for a human readable + description of the asset when providing the contract offer catalog for the consumer and make it easier and readable + for a human what kind of data this asset contains. +- The asset definition MUST contain a property “asset.properties.asset:prop:version” containing a version number to + identify if there have been updates on an asset definition. +- The latter MUST have a property “dataAddress.properties.baseUrl” with a value containing the URL of the endpoint where + the function “GetProductionForecastData” is implemented. +- Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the + possibility to use connectors compliant to \[CX-0018\] as a reverse proxy by adding parameters to the URL. + +The API version described in this standard document MUST be published in the +property `` as version 2.0 in the asset. The requester of an asset +MUST be able to handle multiple assets for this endpoint, being differentiated only by the version. The requester SHOULD +choose the asset with the highest compatible version number implemented by themselves. If the requester cannot find a +compatible version with their own, the requester MUST terminate the data transfer. + +Each supplier MUST ensure that only their customers have access to the asset by using access and usage policies and +respective contract definitions. + +An example Tractus-X Data Asset definition with corresponding access / usage policies and a contract definition is shown +below. Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +**Asset definition**: + +```json +{ + "@context": { + "": "[https://w3id.org//v0.0.1/ns/](https://w3id.org/edc/v0.0.1/ns/)", + "cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)", + "cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)", + "dct": "" + }, + "@id": "sis-request-production-forecast-01", + "properties": { + "description": "Request Production Forecast Asset", + "privateProperties": {}, + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{SIS_REQUEST_PRODUCTION_FORECAST_ENDPOINT}}", + "method": "GET", + "proxyPath": "true", + "contentType": "application/json" + } +} +``` + +**Access and Usage Policy definition**: + +```json +{ + "@context": { + "@vocab": "[https://w3id.org//v0.0.1/ns/](https://w3id.org/edc/v0.0.1/ns/)" + }, + "@id": "sis-request-production-forecast-01-policy", + "policy": { + "@context": [ + "", + { + "cx-policy": "" + } + ], + "@type": "Policy", + "profile": "cx-policy:profile2405", + "permission": [ + { + "action": "use", + "constraint": { + "or": [ + { + "leftOperand": "BusinessPartnerNumber", + "operator": "eq", + "rightOperand": "{{POLICY_BPN}}" + } + ] + } + } + ] + } +} +``` + +**Contract definition**: + +```json +{ + "@context": {}, + "@id": "sis-request-production-forecast-01-contract", + "@type": "ContractDefinition", + "accessPolicyId": "sis-request-production-forecast-01-policy", + "contractPolicyId": "sis-request-production-forecast-01-policy", + "assetsSelector" : { + "@type" : "CriterionDto", + "operandLeft": "https://w3id.org//v0.0.1/ns/id", + "operator": "=", + "operandRight": "sis-request-production-forecast-01" + } +} +``` + +#### 4.1.2.3 ERROR HANDLING + +Every API endpoint defined in Chapter 4.1.2.11 MUST respond to incoming requests with HTTP status codes as described in +\[RFC9110\]. The status codes for each endpoint are defined in the following sections. + +| Status Code | Description | Usage | +| ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | The request has succeeded. | +| 201 | OK, Precision not possible | The request has succeeded. Precision is not possible, the default precision will be used | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. | +| 403 | Forbidden | The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. | +| 420 | Unknown BPNS | The BPNS which is given as parameter is not registered in the data provider database as a direct partner. | +| 421 | Invalid CustomerId | The customerID unknown or invalid | +| 422 | Invalid OrderId | The orderID not found or invalid | +| 423 | Invalid Notification Interval | The data field Notification interval is not set with a proper value or missing | +| 424 | Invalid Deviation | The data field Deviation is not set with a proper value or missing | +| 425 | Forbidden | The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. | +| 426 | incomplete Request | | + +### 4.2 "ProvideProductionForecastData" API + +The ProvideProductionForecastData API sends the forecast data from a Modular Production to the customer or a third party +on the next lower level. All participants using the Shop-Floor-Information-Service in the role of a a Modular Production +MUST be able to send the ProvideProductionForecastData. All participants using the Shop-Floor-Information-Service in the +role of a customer or additional third party MUST be able to receive and process the ProvideProductionForecastData. + +#### 4.2.1 PRECONDITIONS AND DEPENDENCIES + +The ProvideProductionForecastData API MUST be published towards the network using a Data Asset/Contract Offer in terms +of the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC). + +#### 4.2.2 API SPECIFICATION + +#### 4.2.2.1 API Endpoints & resources + +When sending a request to the ProvideProductionForecastData Endpoint, the body MUST be composed out of two information +objects: a *header* and *content*. Together they form the HTTP body that MUST be formatted as JSON Request Header. + +> Note: This is not the HTTP Header but rather part of the HTTP Body. + +| Field | Level | REQUIRED | Purpose | Datatype | Example Value | +| ------------------- | ----------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------- | +| version | CX-header | mandatory | of Meta model used for compatibility | string | 2.0.0 | +| messageId | CX-header | mandatory | unique ID for message will be used as requestID for the following communication | UUID | 00000000-0000-0000-C000-000000000046 | +| context | CX-header | mandatory | Information about the context the message should be considered in, e.g. "MP-Request" | string | MUST BEurn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0 | +| sentDateTime | CX-header | mandatory | time of request | string | 2023-06-19T21:24:00+07:00 | +| senderBpn | CX-header | mandatory | identification of the sender | string | BPNL1234567890SE | +| recipientBpn | CX-header | mandatory | identification of the recipient | string | BPNL0987654321RE | +| expectedResponseBy | CX-header | mandatory | Deadline for the first response | date | 2023-07-02T13:00:00.000+02:00 | +| relatedMessageId | CX-header | optional | not used for request; will be used in the following parts to refer to the request | UUID | 00000000-0000-0000-C000-000000000042 | +| version | SIS-Payload | mandatory | version of the datamodel | string | 2.0.0 | +| iterationNo | SIS-Payload | optional | in case of cyclic or notification mode this field is used to count the iterations to keep them in the correct order | int | 42 | +| communicationMode | SIS-Payload | mandatory | Enum describing if synchronous, cyclic or notification is used for data exchange | enum | synchronous | +| ListOfForecastItems | SIS-Payload | mandatory | list containing the items corresponding to the order of this request | List of Forecast Items | | +| ForecastItem\* | SIS-Payload | | | | | +| positionId | SIS-Payload | mandatory | field referring to the ID of this item in the order list, e.g. item number in case of productionForecastForAll =true : provide order ID instead of position ID | UUID / string | 0007-3 | +| productionForecast | SIS-Payload | mandatory | date of finalizing the production, this does not cover additional internal activities e.g. logistic | datetime | 2023-07-05T14:05:00.000+02:00 | +| precisionOfForecast | SIS-Payload | mandatory | precision of the forecast in form of an interval e.g. +-3days, the precision either matches to the required precision of the request or the maximal possible precision. | TimeValue \[EnumTimeUnits, uint \] | \{ "timeUnit": "day", "value": 3 \}, | +| productionStatus | SIS-Payload | mandatory/opt | status of the production | enum \ | itemReceived | +| forecastDate | SIS-Payload | mandatory | date of determination the forecasting status | datetime | 2023-07-01T14:05:20.255+02:00 | +| reasonForDelay | SIS-Payload | mandatory | in case of a delay a possible explanation | enum | supplyProblems | + +The following JSON object provides an example of a valid header and payload: + +```json +{ + "header": { + "senderBpn": "BPNL7588787849VQ", + "relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy": "2023-06-19T21:24:00+07:00", + "context": "urn:samm:io.catenax.shopfloor_information.provide_production_forecast:2.0.0", + "messageId": "3b405-e214-47a1-b0c2-1d831cdd9ba9", + "recipientBpn": "BPNL6666787765VQ", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "2.0.0" + }, + "productionForecastResponse": { + "listOfForecastItems": [ + { + "returnCode": "ok", + "precisionOfForecast": { + "value": 12, + "timeUnit": "unit:secondUnitOfTime" + }, + "reasonsForDelay": "supplyProblems", + "positionId": "00000000-0000-0000-C000-000000000046", + "productionStatus": "itemReceived", + "productionForecast": "2023-06-19T21:24:00+07:00", + "forecastDate": "2023-06-19T21:24:00+07:00" + } + ], + "version": "2.0.0", + "communicationMode": "synchronous", + "iterationNumber": 6 + } +} +``` + +**Available Data Types**: + +- The API MUST use JSON as the payload transported via HTTPS. More information on the data objects supported by the + endpoints is provided in the corresponding sections of Section 3.2. +- The API ProvideProductionForecastData call MUST use the ProvideProductionForecast data model defined in section 3.2. +- Communication Mode MUST be one of the following items: synchronous, cyclic and notification. +- EnumTimeUnits MUST be one of the following items: unit:secondUnitOfTime, unit:minuteUnitOfTime, unit:hour, unit:day, + unit:week, unit:month, unit:year. +- ProductionStatus MUST be one of the following items: itemReceived, itemPlanned, itemInProduction,itemCompleted, + statusUndefined. +- reasonsForDelay MUST be one of the following items: supplyProblems, internalProblems, otherCircumstances, + noInformationAvailable. + +#### 4.2.2.2 DATA ASSET STRUCTURE + +The HTTP POST endpoint introduced in chapter 4.2.1 MUST NOT be called from a partner directly. Rather, it MUST be called +via a data connection compliant to \[CX-0018\] communication. Therefore, the endpoint MUST be offered as an Data Asset. + +- The latter MUST have a property “asset.properties.asset:prop:id”. This property MUST be used to identify the asset + when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects + the contractual relationship between Shop-Floor-Information-Service partners, only one asset with the aforementioned + property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen + freely but must be unique. +- The asset definition SHOULD contain a property “asset.properties.asset:prop.description” for a human readable + description of the asset when providing the contract offer catalog for the consumer and make it easier and readable + for a human what kind of data this asset contains. +- The asset definition MUST contain a property “asset.properties.asset:prop:version” containing a version number to + identify if there have been updates on an asset definition. +- The latter MUST have a property “dataAddress.properties.baseUrl” with a value containing the URL of the endpoint where + the function “ProvideProductionForecast” is implemented. +- Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the + possibility to use a connector compliant with \[CX-0018\] as a reverse proxy by adding parameters to the URL. + +An example Data Asset definition with a corresponding access / usage policy and contract definition are shown below. +Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +**Asset definition**: + +```json +{ + "@context": { + "edc": "", + "cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)", + "cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)", + "dct": "" + }, + "@id": "sis-provide-production-forecast-01", + "properties": { + "description": "Provide Production Forecast Asset", + "privateProperties": {}, + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{SIS_PROVIDE_PRODUCTION_FORECAST_ENDPOINT}}", + "method": "POST", + "proxyPath": "true", + "contentType": "application/json" + } +} +``` + +**Access and Usage Policy definition**: + +```json + +{ + "@context": { + "@vocab": "" + }, + "@id": "sis-provide-production-forecast-01-policy", + "policy": { + "@context": [ + "", + { + "cx-policy": "" + } + ], + "@type": "Policy", + "profile": "cx-policy:profile2405", + "permission": [ + { + "action": "use", + "constraint": { + "or": [ + { + "leftOperand": "BusinessPartnerNumber", + "operator": "eq", + "rightOperand": "{{POLICY_BPN}}" + } + ] + } + } + ] + } +} +``` + +**Contract definition**: + +```json +{ + "@context": {}, + "@id": "sis-provide-production-forecast-01-contract", + "@type": "ContractDefinition", + "accessPolicyId": "sis-provide-production-forecast-01-policy", + "contractPolicyId": "sis-provide-production-forecast-01-policy", + "assetsSelector" : { + "@type" : "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "sis-provide-production-forecast-01" + } +} +``` + +### 4.3 "Unsubscribe" API + +The Unsubscribe API contains the request to stop transferring forecasting data which is sent from a Modular Production +to a customer or a third party on the next lower level. All participants using the Shop-Floor-Information-Service in the +role of a a customer or third party MUST be able to send the unsubscribe request. All participants using the +Shop-Floor-Information-Service in the role of a Modular Production MUST be able to receive and process the unsubscribe +request. + +#### 4.3.1 PRECONDITIONS AND DEPENDENCIES + +#### 4.3.2 API SPECIFICATION + +The GetProductionForecastData API MUST be published towards the network using a Data Asset/Contract Offer in terms of +the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC). + +#### 4.3.2.1 API Endpoints & resources + +The Unsubscribe API MUST be published towards the network using a Data Asset/Contract Offer in terms of the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC). + +#### 4.3.2.2 DATA ASSET STRUCTURE + +The HTTP DELETE endpoint introduced in chapter 4.3 MUST NOT be called from a partner directly. Rather, it MUST be called +via a connector conformant to \[CX-0018\] like Tractus-X EDC communication. Therefore, the endpoint MUST be offered as +an Data Asset. + +- The latter MUST have a property “asset.properties.asset:prop:id”. This property MUST be used to identify the asset + when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects + the contractual relationship between Shop-Floor-Information-Service partners, only one asset with the aforementioned + property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen + freely but must be unique. +- The asset definition SHOULD contain a property “asset.properties.asset:prop.description” for a human readable + description of the asset when providing the contract offer catalog for the consumer and make it easier and readable + for a human what kind of data this asset contains. +- The asset definition MUST contain a property “asset.properties.asset:prop:version” containing a version number to + identify if there have been updates on an asset definition. +- The latter MUST have a property “dataAddress.properties.baseUrl” with a value containing the URL of the endpoint where + the function “unsubscribe” is implemented. +- Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the + possibility to use the data connectorcompliant to CS-0018 as a reverse proxy by adding parameters to the URL. + +An example Data Asset definition with a corresponding access / usage policy and contract definition are shown below. +Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +**Asset definition**: + +```json +{ + "@context": { + "edc": "", + "cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)", + "cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)", + "dct": "" + }, + "@id": "sis-unsubscribe-production-forecast-01", + "properties": { + "description": "Unsubscribe Production Forecast Asset", + "privateProperties": {}, + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{SIS_UNSUBSCRIBE_PRODUCTION_FORECAST_ENDPOINT}}", + "method": "DELETE", + "proxyPath": "true", + "contentType": "application/json" + } +} +``` + +**Access and Usage Policy definition**: + +```json +{ + "@context": { + "@vocab": "" + }, + "@id": "sis-unsubscribe-production-forecast-01-policy", + "policy": { + "@context": [ + "", + { + "cx-policy": "" + } + ], + "@type": "Policy", + "profile": "cx-policy:profile2405", + "permission": [ + { + "action": "use", + "constraint": { + "or": [ + { + "leftOperand": "BusinessPartnerNumber", + "operator": "eq", + "rightOperand": "{{POLICY_BPN}}" + } + ] + } + } + ] + } +} +``` + +**Contract definition**: + +```json +{ + "@context": {}, + "@id": "sis-unsubscribe-production-forecast-01-contract", + "@type": "ContractDefinition", + "accessPolicyId": "sis-unsubscribe-production-forecast-01-policy", + "contractPolicyId": "sis-unsubscribe-production-forecast-01-policy", + "assetsSelector" : { + "@type" : "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "sis-unsubscribe-production-forecast-01" + } +} +``` + +#### 4.3.2.3 ERROR HANDLING + +Every API endpoint defined in Chapter 4.3.1 MUST respond to incoming requests with HTTP status codes as described in +\[RFC9110\]. The status codes for each endpoint are defined in the following sections. + +| Status Code | Description | Usage | +| ----------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | The request has succeeded. Unsubscribe was successful | +| 400 | Bad Request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. | +| 403 | Forbidden | The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. | +| 420 | Unknown relatedMessageID | The combination of relatedMessageId and BPNS does not fit | + +### 4.4 "GetProductionTrackingData" API + +**This introduction holds for 4.4-4.5**: + +The GetProductionTrackingData contains the request for tracking data which is sent from a Modular Production partner to +a customer or a third party on the next lower level. All participants using the Shop-Floor-Information-Service in the +role of a a customer or third party MUST be able to send the GetProductionTrackingData . All participants using the +Shop-Floor-Information-Service in the role of a Modular Production MUST be able to receive and process the +GetProductionTrackingData . + +The following diagram shows the complete communication between the partners in a abstract way. It takes place in +different phases: + +1. **Negotiation** between the data connectors of the partners like Tractus-X EDC using the needed policies. +1. GetProductionTrackingData(...) - the call of the customer. +1. get the desired information via ProvideProductionTrackingData(...) - transfered by Modular Production. + +![SIS Tracking](./assets/SIS.Tracking.AD.png) + +#### 4.4.1 PRECONDITIONS AND DEPENDENCIES + +#### 4.4.2 API SPECIFICATION + +The GetProductionTrackingData API MUST be published towards the network using a Data Asset/Contract Offer in terms of +the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC). + +#### 4.4.2.1 API Endpoints & resources + +When sending a request to the GetProductionTrackingData Endpoint, the body MUST be composed out of two information +objects: a header and a content. Together they form the HTTP body that MUST be formatted as JSON Request Header. + +| Field | Level | Required | Purpose | Datatype | Example Value | +| -------------------------- | ----------- | --------- | --------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------ | +| header | | | | | | +| senderBpn | CX-Header | mandatory | of Meta Model used for compatibility | BpnlCharacteristic | BPNL1234567890SE | +| version | CX-header | mandatory | of Meta model used for compatibility | VersionCharacteristic | 2.0.0 | +| messageId | CX-header | mandatory | unique ID for message will be used as requestID for the following communication | UUID | 00000000-0000-0000-C000-000000000046 | +| context | CX-header | mandatory | Information about the context the message should be considered in, e.g. "MP-Request" | string | MUST BE urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0 | +| sentDateTime | CX-header | mandatory | time of request | string | 2023-06-19T21:24:00+07:00 | +| recipientBpn | CX-header | mandatory | identification of the recipient | BpnlCharacteristic | BPNL0987654321RE | +| expectedResponseBy | CX-header | mandatory | Deadline for the first response | date | 2023-07-02T13:00:00.000+02:00 | +| relatedMessageId | CX-header | optional | not used for request; will be used in the following parts to refer to the request | UUID | 00000000-0000-0000-C000-000000000042 | +| request | | | | | | +| version | SIS-Payload | mandatory | of Meta model used for compatibility | VersionCharacteristic | 1.0.0 | +| customerId | SIS-Payload | mandatory | internal customer number | string | 550e8400-e29b-41d4-a716-446655440000 | +| catenaXId | SIS-Payload | optional | identifier of a product that is registered in a catena-x digital twin registry | uuid | urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379 | +| identifierType | SIS-Payload | mandatory | specifies the kind of the identifierNumber | enum | partInstanceId | +| identifierNumber | SIS-Payload | mandatory | identifier of a product | string | box-12345678 | +| processReferenceType | SIS-Payload | mandatory | determines whether a process step is identified with a capability or a processStepIdentifier of a billOfProcess | string | processStep | +| billOfProcessId | SIS-Payload | optional | identifier of a bill of process known by both partners | string | box-with-lid-12345678-bill-of-process | +| stepIdentifierList | SIS-Payload | mandatory | lists all process steps from which parameters are requested | list | | +| capabilityId | SIS-Payload | optional | identifier of a capability | string | Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben | +| partInstanceLevel | SIS-Payload | optional | determines whether a sub-product is identified based on a bill of material or a partInstanceId | enum | partInstanceId | +| billOfMaterialId | SIS-Payload | optional | identifier of a bill of material | string | 321-BomIdentifier | +| billOfMaterialElementId | SIS-Payload | optional | identifies a concrete element of the bill of material referenced with the billOfMaterialId | string | Deckel-Bom-123-Schraube | +| partInstanceId | SIS-Payload | optional | partInstanceId to identify a sub-product of a product | string | Deckel-Serial-123 | +| processStepId | SIS-Payload | optional | identifier of a process step referenced in the billOfProcessId | string | Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01 | +| processParameterList | SIS-Payload | mandatory | Lists all process Parameter requested from a process step | list | | +| processParameterName | SIS-Payload | mandatory | name of a requested process parameter | string | Drehmoment_Max | +| processParameterSemanticId | SIS-Payload | mandatory | link to a semantic that characterizes the type of the process parameter | string | 0173-1#02-ABK233#001 | + +The following JSON object gives an example of a valid data model: + +```json +{ + "request" : { + "identifierNumber" : "box-12345678", + "stepIdentifierList" : [ { + "processStepId" : "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01", + "processParameterList" : [ { + "processParameterSemanticId" : "0173-1#02-ABK233#001", + "processParameterName" : "Drehmoment_Max" + } ] + } ], + "customerId" : "550e8400-e29b-41d4-a716-446655440000", + "identifierType" : "partInstanceId", + "billOfProcessId" : "box-with-lid-12345678-bill-of-process", + "version" : "1.0.0", + "processReferenceType" : "processStep" + }, + "header" : { + "senderBpn" : "BPNL7588787849VQ", + "relatedMessageId" : "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy" : "2023-06-19T21:24:00+07:00", + "context" : "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0", + "messageId" : "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn" : "BPNL6666787765VQ", + "sentDateTime" : "2023-06-19T21:24:00+07:00", + "version" : "2.0.0" + } +} + +``` + +**Available Data Types**: + +- The API MUST use JSON as the payload transported via HTTPS. More information on the data objects supported by the + endpoints is provided in the corresponding sections of Section 3.4. +- The API GetProductionTrackingData call MUST use the ProvideProductionForecast data model defined in 3.4. +- IdentifierType MUST be one of the following items: partInstanceId, batchId, billOfMaterialId. +- processReferenceType Mode MUST be one of the following items: processStep, capability. +- partInstanceLevel MUST be one of the following items: partInstanceId, billOfMaterialId. + +#### 4.4.2.2 DATA ASSET STRUCTURE + +The HTTP GET endpoint introduced in chapter 4.4.1 MUST NOT be called from a partner directly. Rather, it MUST be called +via a connector as defined in \[CX-0018\]. Therefore, the endpoint MUST be offered as an Data Asset. + +- The latter MUST have a property “asset.properties.asset:prop:id”. This property MUST be used to identify the asset + when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects + the contractual relationship between Shop-Floor-Information-Service partners, only one asset with the aforementioned + property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen + freely but must be unique. +- The asset definition SHOULD contain a property “asset.properties.asset:prop.description” for a human readable + description of the asset when providing the contract offer catalog for the consumer and make it easier and readable + for a human what kind of data this asset contains. +- The asset definition MUST contain a property “asset.properties.asset:prop:version” containing a version number to + identify if there have been updates on an asset definition. +- The latter MUST have a property “dataAddress.properties.baseUrl” with a value containing the URL of the endpoint where + the function “unsubscribe” is implemented. +- Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the + possibility to use the connector compliant with \[CX-0018\] as a reverse proxy by adding parameters to the URL. + +An example Data Asset definition with a corresponding access / usage policy and contract definition are shown below. +Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +**Asset definition**: + +```json +{ + "@context": { + "edc": "", + "cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)", + "cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)", + "dct": "" + }, + "@id": "sis-get-production-tracking-01", + "properties": { + "description": "Get Production Tracking Asset", + "privateProperties": { + }, + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{SIS\_GET\_PRODUCTION\_FORECAST\_TRACKING}}", + "method": "GET", + "proxyPath": "true", + "contentType": "application/json" + } +} +``` + +**Access and Usage Policy definition**: + +```json +{ + "@context": { + "@vocab": "" + }, + "@id": "sis-get-production-tracking-01-policy", + "policy": { + "@context": [ + "", + { + "cx-policy": "" + } + ], + "@type": "Policy", + "profile": "cx-policy:profile2405", + "permission": [ + { + "action": "use", + "constraint": { + "or": [ + { + "leftOperand": "BusinessPartnerNumber", + "operator": "eq", + "rightOperand": "{{POLICY_BPN}}" + } + ] + } + } + ] + } +} +``` + +**Contract definition**: + +```json +{ + "@context": {}, + "@id": "sis-get-production-tracking-01-contract", + "@type": "ContractDefinition", + "accessPolicyId": "sis-get-production-tracking-01-policy", + "contractPolicyId": "sis-get-production-tracking-01-policy", + "assetsSelector" : { + "@type" : "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "sis-get-production-tracking-01" + } +} +``` + +#### 4.4.2.3 ERROR HANDLING + +Every API endpoint defined in Chapter 4.4.1 MUST respond to incoming requests with HTTP status codes as described in +\[RFC9110\]. The status codes for each endpoint are defined in the following sections. + +| Status Code | Description | Usage | +| ----------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | The request has succeeded. | +| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). | +| 401 | Unauthorized | Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. | +| 402 | Unknown BPNS | The BPNS which is given as parameter is not registered in the data provider database as a direct partner. | +| 403 | CustomerId unknown | The customerID unknown | +| 405 | Forbidden | The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. | +| 421 | uncomplete Request | | +| 422 | identifierNumber unknown | The identifierID unknown | +| 423 | billOfMaterialId unknown | The billOfMaterialId unknown | +| 424 | billOfProcessId unknown | The billOfProcessId unknown | +| 425 | bomElementId unknown | The bomElementId unknown | +| 426 | capabilityId unknown | The capabilityId unknown | +| 427 | processStepId unknown | The processStepId unknown | +| 428 | other parameters unknown | Other parameters unknown | + +### 4.5 "ProvideProductionTrackingData" API + +The ProvideProductionTrackingDataAPI sends the forecasting data from a Modular Production to the customer or a third +party on the next lower level. All participants using the Shop-Floor-Information-Service in the role of a a Modular +Production MUST be able to send the ProvideProductionForecastData. All participants using the +Shop-Floor-Information-Service in the role of a customer or additional third party MUST be able to receive and process +the ProvideProductionForecastData. + +#### 4.5.1 PRECONDITIONS AND DEPENDENCIES + +The ProvideProductionTrackingDataAPI MUST be published towards the network using a Data Asset/Contract Offer in terms of +the Dataspace Protocol as defined by IDSA, following the CX-0018 Eclipse Data Space Connector (EDC). + +#### 4.5.2 API SPECIFICATION + +#### 4.5.2.1 API Endpoints & resources + +When sending a request to the ProvideProductionForecastData Endpoint, the body MUST be composed out of two information +objects: a header and a content. Together they form the HTTP body that MUST be formatted as JSON Request Header. + +> Note: This is not the HTTP Header but rather part of the HTTP Body. + +| Field | Level | Required | Purpose | Datatype | Example Value | +| -------------------------- | ----------- | --------- | ------------------------------------------------------------------------------------ | --------------------- | ---------------------------------------------------------------------------------- | +| header | | | | | | +| senderBpn | CX-Header | mandatory | of Meta Model used for compatibility | BpnlCharacteristic | BPNL1234567890SE | +| version | CX-header | mandatory | of Meta model used for compatibility | VersionCharacteristic | 2.0.0 | +| messageId | CX-header | mandatory | unique ID for message will be used as requestID for the following communication | UUID | 00000000-0000-0000-C000-000000000046 | +| context | CX-header | mandatory | Information about the context the message should be considered in, e.g. "MP-Request" | string | MUST BEurn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0 | +| sentDateTime | CX-header | mandatory | time of request | string | 2023-06-19T21:24:00+07:00 | +| recipientBpn | CX-header | mandatory | identification of the recipient | BpnlCharacteristic | BPNL0987654321RE | +| expectedResponseBy | CX-header | mandatory | Deadline for the first response | date | 2023-07-02T13:00:00.000+02:00 | +| relatedMessageId | CX-header | optional | not used for request; will be used in the following parts to refer to the request | UUID | 00000000-0000-0000-C000-000000000042 | +| response | | | | | | +| version | SIS-Payload | mandatory | of Meta model used for compatibility | VersionCharacteristic | 1.0.0 | +| catenaXId | SIS-Payload | optional | identifier of a product that is registered in a catena-x digital twin registry | uuid | urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379 | +| identifierType | SIS-Payload | mandatory | specifies the kind of the identifierNumber | enum | partInstanceId | +| identifierNumber | SIS-Payload | mandatory | identifier of a product | string | box-12345678 | +| processStepIdentifierList | SIS-Payload | mandatory | Lists all process steps for which parameters are provided | list | | +| processStepId | SIS-Payload | optional | identifier of a process step referenced in the billOfProcessId | string | Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01 | +| processParameterValueList | SIS-Payload | mandatory | Lists all process Parameter provided for a process step | list | | +| processParameterName | SIS-Payload | mandatory | name of a requested process parameter | string | Drehmoment_Max | +| processParameterSemanticId | SIS-Payload | mandatory | link to a semantic that characterizes the type of the process parameter | string | 0173-1#02-ABK233#001 | +| processParameterValue | SIS-Payload | mandatory | the concrete value of a process parameter | string | 10 | +| processParameterQuality | SIS-Payload | mandatory | indicates the quality of the parameters value measurement | enum | noValue | + +The following JSON object gives an example of a valid header and payload. + +```json +{ + "header" : { + "senderBpn" : "BPNL7588787849VQ", + "relatedMessageId" : "d9452f24-3bf3-4134-b3eb-68858f1b2362", + "expectedResponseBy" : "2023-06-19T21:24:00+07:00", + "context" : "urn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0", + "messageId" : "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn" : "BPNL6666787765VQ", + "sentDateTime" : "2023-06-19T21:24:00+07:00", + "version" : "2.0.0" + }, + "response" : { + "identifierNumber" : "box-12345678", + "catenaXId" : "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", + "identifierType" : "partInstanceId", + "version" : "1.0.0", + "processStepIdentifierList" : [ { + "processStepId" : "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01", + "processParameterValueList" : [ { + "processParameterName" : "Drehmoment_Max", + "semanticId" : "0173-1#02-ABK233#001", + "processParameterQuality" : "ok", + "processParameterValue" : "10" + } ] + } ] + } +} +``` + +**Available Data Types**: + +- The API MUST use JSON as the payload transported via HTTPS. More information on the data objects supported by the + endpoints is provided in the corresponding sections of Section 4.4.1. +- The API ProvideProductionTrackingDatacall MUST use the ProvideProductionTrackingData data model as described in 4.4.1. +- processParameterQuality MUST be one of the following items: ok, inexact, noValue. + +#### 4.5.2.2 DATA ASSET STRUCTURE + +The HTTP POST endpoint introduced in chapter 4.5.1 MUST NOT be called from a partner directly. Rather, it MUST be called +via a connector compliant with \[CX-0018\] communication. Therefore, the endpoint MUST be offered as an Data Asset. + +- The latter MUST have a property “asset.properties.asset:prop:id”. This property MUST be used to identify the asset + when searching the assets catalog of a supplier as well as initiating a transfer process. Because the asset reflects + the contractual relationship between Shop-Floor-Information-Service partners, only one asset with the aforementioned + property MUST be visible to the customer at any time to avoid ambiguity. The value for this property can be chosen + freely but must be unique. +- The asset definition SHOULD contain a property “asset.properties.asset:prop.description” for a human readable + description of the asset when providing the contract offer catalog for the consumer and make it easier and readable + for a human what kind of data this asset contains. +- The asset definition MUST contain a property “asset.properties.asset:prop:version” containing a version number to + identify if there have been updates on an asset definition. +- The latter MUST have a property “dataAddress.properties.baseUrl” with a value containing the URL of the endpoint where + the function “ProvideProductionForecast” is implemented. +- Additionally, the dataAddress property MUST contain the parameter proxyPath with a value set to TRUE to enable the + possibility to use a connector compliant with \[CX-0018\] as a reverse proxy by adding parameters to the URL. + +An example Data Asset definition with a corresponding access / usage policy and contract definition are shown below. +Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +**Asset definition**: + +```json +{ + "@context": { + "edc": "", + "cx-common": "[https://w3id.org/catenax/ontology/common#](https://w3id.org/catenax/ontology/common)", + "cx-taxo": "[https://w3id.org/catenax/taxonomy#](https://w3id.org/catenax/taxonomy)", + "dct": "" + }, + "@id": "sis-provide-production-tracking-01", + "properties": { + "description": "Provide Production Tracking Asset", + "privateProperties": {}, + "cx-common:version": "2.0" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{SIS_PROVIDE_PRODUCTION_FORECAST_TRACKING}}", + "method": "POST", + "proxyPath": "true", + "contentType": "application/json" + } +} +``` + +**Access and Usage Policy definition**: + +```json +{ + "@context": { + "@vocab": "" + }, + "@id": "sis-provide-production-tracking-01-policy", + "policy": { + "@context": [ + "", + { + "cx-policy": "" + } + ], + "@type": "Policy", + "profile": "cx-policy:profile2405", + "permission": [ + { + "action": "use", + "constraint": { + "or": [ + { + "leftOperand": "BusinessPartnerNumber", + "operator": "eq", + "rightOperand": "{{POLICY_BPN}}" + } + ] + } + } + ] + } +} +``` + +**Contract definition**: + +```json +{ + "@context": {}, + "@id": "sis-provide-production-tracking-01-contract", + "@type": "ContractDefinition", + "accessPolicyId": "sis-provide-production-tracking-01-policy", + "contractPolicyId": "sis-provide-production-tracking-01-policy", + "assetsSelector" : { + "@type" : "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "sis-provide-production-tracking-01" + } +} +``` + +## 5 PROCESSES + +> *This section is normative* + +### 5.1 "Production Forecast" PROCESS + +#### 5.1.1 ACTORS AND ROLES + +Any application provider that develops the Production Forecast Aspect of the Shop-Floor-Information-Service has to grant +fulfilllment of these requirements. + +- The solution MUST be designed to consider requirements for a trusted usage environment (e.g., identity verification + and /or verification process). +- The solution MUST be designed to require a contractual agreement in compliance with antitrust requirements in the + usage environment (e.g., data contracts as a prerequisite for carrying out a data exchange). For reference see CX-0001 + guidelines. +- The solution MUST be designed to limit visibility and/or access to concrete data content as much as possible (e.g., + data offer does not yet allow data access). +- The solution MUST be designed to require the implementation of notice and/or acknowledgement concepts to raise + awareness of antitrust issues during use (e.g., helpdesk or pop-up info). +- The solution MUST be designed to ensure traceability/reconstructability of processes through appropriate documentation + and at the same time data sovereignty over concrete data content (e.g., through access, deletion or destination + rights). + +Any **Modular Production, their customer involved logistician** and subcontractors (in following called with “all +parties”) **in the Shop-Floor-Information Production Forecast Service process** (i.e., data provider and/or data +consumer) MUST fulfill following requirements: + +- All parties are in a contractual relationship with each other and MUST agree to share data related using the + Production Forecasts Aspects of the Shop-Floor-Information-Service. +- All parties MUST manage the access authorization to the Production Forecast Shop-Floor-Information-Service and to its + related data. +- All parties MUST be technically able to participate within the Production Forecast Aspect of + Shop-Floor-Information-Service Process. +- All parties in the role of data provider MUST be able to generate Shop-Floor-Information like forecasting information + on the production as well as the current production state. Internal planning data of a Modular Production MUST be made + accessible by authorized data consumers (e.g., logisticians or customers) of an upper level in the supply chain. +- All data providers (factories) MUST ensure that the authorized data consumers will get data directly relevant to them + only. +- All parties in the role of data consumer MUST be able to request and receive data from the factory. Data MUST be + exchanged either on request, cyclic and or on notification if a state is changing. +- It is RECOMMENDED to share forecasting information of a time window of 1 week. + +### 5.2 "Production Tracking" PROCESS + +#### 5.2.1 ACTORS AND ROLES + +Any application provider that develops the Production Tracking Aspect of the Shop-Floor-Information-Service has to grant +fulfillment of these requirements. + +- The solution MUST be designed to consider requirements for a trusted usage environment (e.g., identity verification + and /or verification process). +- The solution MUST be designed to require a contractual agreement in compliance with antitrust requirements in the + usage environment (e.g., data contracts as a prerequisite for carrying out a data exchange). For reference see CX-0001 + guidelines. +- The solution MUST be designed to limit visibility and/or access to concrete data content as much as possible (e.g., + data offer does not yet allow data access). +- The solution MUST be designed to require the implementation of notice and/or acknowledgement concepts to raise + awareness of antitrust issues during use (e.g., helpdesk or pop-up info). +- The solution MUST be designed to ensure traceability/reconstructability of processes through appropriate documentation + and at the same time data sovereignty over concrete data content (e.g., through access, deletion or destination + rights). + +Any **Modular Production, their customer** **in the Production Tracking Aspect of the Shop-Floor-Information Service +process** (i.e., data provider and/or data consumer) MUST fulfilll following requirements: + +- All parties are in a contractual relationship with each other and MUST agree to share data related using the + Production Tracking related aspects of the Shop-Floor-Information-Service +- All parties MUST manage the access authorization to the Production Tracking Shop-Floor-Information-Service and to its + related data. +- All parties MUST be technically able to participate within the Production Tracking Aspect of the + Shop-Floor-Information-Service Process. +- All parties in the role of data provider MUST be able to generate Shop-Floor-Information like tracking information + during the production +- All data providers (factories) MUST ensure that the authorized data consumers will get data directly relevant to them + only. +- All parties in the role of data consumer MUST be able to request and receive data from the factory. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normative* + +- CX-0001 EDC Discovery API* Version 1.0.2 +- CX-0003 SAMM Aspect Meta Model Version 1.1.0 or 1.0.2 +- CX-0010 Business Partner Number Version 2.0.0 +- CX-0018 Dataspace Connectivity Version 3.0.0 + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +```text + n.a. +``` + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +```text + n.a. +``` + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/ProductionStates.png b/docs/standards/CX-0142-ShopFloorInformationService/assets/ProductionStates.png new file mode 100644 index 000000000..fa5e48b27 Binary files /dev/null and b/docs/standards/CX-0142-ShopFloorInformationService/assets/ProductionStates.png differ diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking new file mode 100644 index 000000000..1550d7872 --- /dev/null +++ b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking @@ -0,0 +1,257 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking.AD b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking.AD new file mode 100644 index 000000000..82121be8b --- /dev/null +++ b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking.AD @@ -0,0 +1,257 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking.AD.png b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking.AD.png new file mode 100644 index 000000000..16502749a Binary files /dev/null and b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking.AD.png differ diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking.png b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking.png new file mode 100644 index 000000000..d9aa3fa33 Binary files /dev/null and b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS.Tracking.png differ diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_Overview.png b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_Overview.png new file mode 100644 index 000000000..7c099c9dd Binary files /dev/null and b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_Overview.png differ diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking new file mode 100644 index 000000000..d2fb72f0b --- /dev/null +++ b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking @@ -0,0 +1,378 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking.png b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking.png new file mode 100644 index 000000000..bd2066ea7 Binary files /dev/null and b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking.png differ diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking_Overview b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking_Overview new file mode 100644 index 000000000..1b2a1509b --- /dev/null +++ b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking_Overview @@ -0,0 +1,129 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking_Overview.png b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking_Overview.png new file mode 100644 index 000000000..908838bb0 Binary files /dev/null and b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking_Overview.png differ diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking_Overview_Border30.svg b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking_Overview_Border30.svg new file mode 100644 index 000000000..3d6be1539 --- /dev/null +++ b/docs/standards/CX-0142-ShopFloorInformationService/assets/SIS_ProductionTracking_Overview_Border30.svg @@ -0,0 +1,3 @@ + + +
    Catena-X
    Customer
    Catena-X...
    Catena-X
    Modular Production
    Catena-X...
    Central Catena-X
    Services
    Central Catena-X...
    Discovery
    Service
    Discovery...
    SSI
    SSI
    BPN Registry
    BPN Registry
    IAM
    IAM
    GetProductionTrackingData
    GetProductionTrackingData
    EDC
    EDC
    EDC
    EDC
    ProvideProductionTrackingData
    ProvideProductionTrackingData
    register
    register
    search
    search
    Data
    Data
    Scheduler
    Scheduler
    other shopfloor services
    other shopflo...
    OPC UA
    OPC UA
    Logger
    Logger    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/drawio-backup-SIS_ProductionTracking-rev-3 b/docs/standards/CX-0142-ShopFloorInformationService/assets/drawio-backup-SIS_ProductionTracking-rev-3 new file mode 100644 index 000000000..3e7c6f18e --- /dev/null +++ b/docs/standards/CX-0142-ShopFloorInformationService/assets/drawio-backup-SIS_ProductionTracking-rev-3 @@ -0,0 +1,378 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/standards/CX-0142-ShopFloorInformationService/assets/image-2024-2-9_15-37-48.png b/docs/standards/CX-0142-ShopFloorInformationService/assets/image-2024-2-9_15-37-48.png new file mode 100644 index 000000000..69a607d36 Binary files /dev/null and b/docs/standards/CX-0142-ShopFloorInformationService/assets/image-2024-2-9_15-37-48.png differ diff --git a/docs/standards/CX-0143-UseCaseCircularEconomyDigitalProductPassportStandard/CX-0143-UseCaseCircularEconomyDigitalProductPassportStandard.md b/docs/standards/CX-0143-UseCaseCircularEconomyDigitalProductPassportStandard/CX-0143-UseCaseCircularEconomyDigitalProductPassportStandard.md new file mode 100644 index 000000000..3a41b0d15 --- /dev/null +++ b/docs/standards/CX-0143-UseCaseCircularEconomyDigitalProductPassportStandard/CX-0143-UseCaseCircularEconomyDigitalProductPassportStandard.md @@ -0,0 +1,745 @@ +# CX-0143 Use Case Circular Economy - Digital Product Passport Standard 1.0.0 + +## ABSTRACT + +This standard focuses on the digital product passport use case. This includes relevant requirements for + +- data provider, that want to provide different passports through Catena-X, +- data consumer, that are searching for different passports in Catena-X, and +- application developer / provider supporting the provisioning and consuming of passport data. + +Specific passports that shall be mentioned here are the battery passport and the transmission passport, which are first realizations of product passports in Catena-X. + +In this document, keywords for registering and searching digital twins and their passports +submodels are defined. + +## FOR WHOM IS THE STANDARD DESIGNED + +See the audience and scope [1.1](#11-audience--scope) + +## 1 INTRODUCTION + +The Digital Product Passport (DPP) allows to share process and product-related information amongst supply chain businesses, authorities and consumers. The DPP allows for efficient information flows following best practices; and the possibility of accompanying the measures under this Regulation with mitigating measures so that impacts are expected to remain proportionate for SMEs. This is expected to increase transparency, both for supply chain businesses and for the general public, and increase efficiencies in terms of information transfer to support the data exchange between economic actors in integrating circularity in product design and manufacturing. In particular, it is likely to help facilitate and streamline the monitoring and enforcement of the regulation carried out by EU and Member State authorities. It is also likely to provide a market-intelligence tool that may be used for revising and refining obligations in the future. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This document is meant for the following roles: + +- Data Provider / Consumer +- Business Application Provider + +The standard is of interest to all members of the automotive supply chain including suppliers, OEMs, dismantler, recyclers and stakeholders within the recycling industry and the circular economy. + +Additionally, the standard also applies to software providers and core service providers to ensure interoperability and data sovereignty between different core service providers. The scope of this standard is to define mandatory components, logics and data models as well as give guidance for the provisioning and consuming of product pass information. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +Manufacturers of physical goods will have to provide information on different aspects of their products, including components or ingredients, information about the manufacturing itself or information relevant to optimize aspects of repair, reusability or recycling. +This information is stored in in an aggregated form in a "passport", providing information on instances of the product. + +Different stakeholders shall be able to read these passports such as legal authorities, dismantler, +as well as the owner of the product in sense of public persons. + +This standards defines the basic interactions with passport information as standard for the +use case "digital product passport". It is implemented in a first reference application which +can be found in section [6.3 REFERENCE IMPLEMENTATION](#63-reference-implementations). + +This image depicts an overall image of the architecture this standard relates to. Further information can be read in the [Eco Pass KIT](https://eclipse-tractusx.github.io/docs-kits/kits/Eco_Pass_KIT/page-adoption-view). +The standards related to these components are mentioned in more detail in +[2.1.1 LIST OF STANDALONE STANDARDS](#211-list-of-standalone-standards). +Further architecture diagrams for the interactions are presented in [FIGURES](#figures). + +![Architectural Overview](./assets/img/digitalProductPassContext.jpg) + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* +> +> As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +> in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to proof, that they are conform with the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +All participants and their solutions will need to proof, that they are conform with the Catena-X standards. +To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). +Please refer to the [certification information page](https://catena-x.net/en/catena-x-introduce-implement/certification) for the process of conformity assessment and certification. +Since this standard document describes a set of standards to be fulfilled, participants MUST fulfill all mentioned standards listed at [2.1.1 LIST OF STANDALONE STANDARDS](#211-list-of-standalone-standards) and the respective conformity assessment criteria in addition to the specific criteria mentioned in this document. The specific criteria described in this document are describing the usage of the central tools as well as common tools described in the linked standardization documents and therefore compliance should be checked with the tools provided for these components. + +In order to proof conformity with this use case digital product pass standard as a +data consumer or app provider demonstrate that you + +- can find digital twins containing passport information in the Catena-X data space +- can distinguish the passport submodel information from other submodels within the digital twin +- are compliant with the consuming conditions in [ADDITIONAL REQUIREMENTS](#213-additional-requirements), [APPLICATION PROGRAMMING INTERFACES](#4-application-programming-interfaces) and [DIGITAL TWINS AND SPECIFIC ASSET IDs](#214-digital-twins-and-specific-asset-ids) + +In order to proof conformity with this use case digital product pass standard as data provider show that you + +- are conform with the provisioning conditions in [ADDITIONAL REQUIREMENTS](#213-additional-requirements), [APPLICATION PROGRAMMING INTERFACES](#4-application-programming-interfaces) and [DIGITAL TWINS AND SPECIFIC ASSET IDs](#214-digital-twins-and-specific-asset-ids) + +### 1.4 EXAMPLES + +> *This section is non-normative* + +The following examples can be checked as they offer further explanations and guidance how to stay compliant with the standard: + +- [Eco Pass KIT](https://eclipse-tractusx.github.io/docs-kits/kits/Eco_Pass_KIT/page-adoption-view) +- [Tractus-X Digital Product Pass Reference Application](#63-reference-implementations) + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +Use case relevant terminologies and explanations can be found in the [Eco Pass KIT](https://eclipse-tractusx.github.io/docs-kits/kits/Eco_Pass_KIT/page-adoption-view) + +The following terms are especially relevant for the understanding of the standard: + +- **Asset Administration Shell (AAS):** The AAS is the chosen standard in Catena-X to define digital twins + of an asset (e.g. a battery or a full vehicle). The AAS, developed by the [Industrial Digital Twin Association](https://industrialdigitaltwin.org/,) is the standardized digital representation of an digital twin asset, the corner stone for the interoperability of Industry 4.0 components organized in Industry 4.0 systems. +- **Business Partner Number (BPN):** A BPN is the unique identifier of a partner within Catena-X as standardized in [CX-0010 Business Partner Number](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0010-BusinessPartnerNumber_v2.0.0.pdf). +- **Ecodesign for Sustainable Products Regulation (ESPR):** The proposed regulation to improve EU products’ circularity, energy performance and other environmental sustainability aspects. +- **Digital Product Passport (DPP):** The Digital Product Passport is the core model of this standard. It can be used as the root class for other, specific, product models. The Passport itself is defined by the usage of Catena-X shared services, a standardized data model and an application which will enable stakeholders to access the relevant data. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normantive* + +### 2.1 "DIGITAL PRODUCT PASS USE CASE" + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +To participate in the digital product passport use case, the following single standards **MUST** +be fulfilled by all participants for which the standard is relevant: + +- [CX-0001 EDC Discovery API v1.0.2](https://catenax-ev.github.io/docs/standards/overview) +- [CX-0002 Digital Twins in Catena - X v2.1.0](https://catenax-ev.github.io/docs/standards/overview) +- [CX-0003 SAMM Semantic Aspect Meta Model v1.1.0](https://catenax-ev.github.io/docs/standards/overview) +- [CX-0005 Item Relationship Service v2.0.0](https://catenax-ev.github.io/docs/standards/overview) +- [CX-0006 Registration and initial onboarding v1.1.3](https://catenax-ev.github.io/docs/standards/overview) +- [CX-0008 Relevant standards for conformity assessments v1.1.0](https://catenax-ev.github.io/docs/standards/overview) +- [CX-0010 BusinessPartnerNumber v2.0.0](https://catenax-ev.github.io/docs/standards/overview) +- [CX-0013 Identity of Member Companies v1.1.0](https://catenax-ev.github.io/docs/standards/overview) +- [CX-0014 Employees and Technical Users v1.0.1](https://catenax-ev.github.io/docs/standards/overview) +- [CX-0015 IAM & Access Control Paradigm v1.0.1](https://catenax-ev.github.io/docs/standards/overview) +- [CX-0018 Eclipse Data Space Connector (EDC) v2.1.0](https://catenax-ev.github.io/docs/standards/overview) +- [CX-0053 BPN Discovery Services v1.1.0](https://catenax-ev.github.io/docs/standards/overview) + +- [CX-0126 Industry Core Part Type v1.0.0](https://catenax-ev.github.io/docs/standards/overview) + +- [CX-0127 Industry Core Part Instance v1.0.0](https://catenax-ev.github.io/docs/standards/overview) + +To participate in the digital product passport use case, the following single standards **SHOULD** +be fulfilled by data consumers / applications providers for which the standard is relevant: + +- [CX-0005 Item Relationship Service API v2.0.0](https://catenax-ev.github.io/docs/standards/overview) + +#### 2.1.2 DATA REQUIRED + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### 2.1.3.1 Onboarding and IAM + +All participant mentioned under [1.1](#11-audience--scope) **MUST** follow the CX Standards +[CX-0006](#211-list-of-standalone-standards), +[CX-0013](#211-list-of-standalone-standards), +[CX-0014](#211-list-of-standalone-standards) and +[CX-0015](#211-list-of-standalone-standards) + +##### 2.1.3.2 Fetching EDC Endpoints + +To find the decentralized registries of related parties in Catena-X, app provider **MUST** follow the [CX-0001](#211-list-of-standalone-standards) standard. + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +##### 2.1.4.1 Searching for Decentralized Digital Twin Registries + +To find decentralized Digital Twin Registries of related parties in Catena-X, app provider **MUST** follow the [CX-0002](#211-list-of-standalone-standards) Standard. + +##### 2.1.4.2 Registration at the BPN Discovery Service + +To find the Business Partner Number of the related parties in Catena-X, data provider **MUST** follow the [CX-0053](#211-list-of-standalone-standards) standard. Example can be found in the [Digital Twin Kit](https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/Specification%20Digital%20Twin%20KIT) + +In specific, as a data provider you **MUST** register the `manufacturerPartId` following the +Catena-X standard [CX-0002](#211-list-of-standalone-standards) at the BPN Discovery Service. +The BPN is hand-over by the authentication/authorization token. Only the owner of a BPN can link the `manufacturerPartId` to their BPN. + +An example can be found here: [Digital Twin Kit - API BPN Discovery](https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/API%20BPN%20Discovery/post-bpn-discovery) + +**Example** + +```text +POST /api/administration/connectors/bpnDiscovery +``` + +```json +{ + "type": "manufacturerPartId", + "key": "12345678910" +} +``` + +**Response** + +```json +{ + "type": "manufacturerPartId", + "key": "12345678910", + "value": "bpn-123", + "resourceId": "1ca6f9b5-8e1d-422a-8541-9bb2cf5fe485" +} +``` + +As an app provider / data consumer you **MUST** use the `manufacturerPartId` to search for related BPN endpoints. +An example can be found here: [Digital Twin Kit - API BPN Discovery](https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/API%20BPN%20Discovery/get-bpn-discoveries) + +**Example** + +```text +POST /api/administration/connectors/bpnDiscovery/search +``` + +```json +{ + "searchFilter": [ + { + "type": "manufacturerPartId", + "keys": ["12345678910"] + } + ] +} +``` + +**Response** + +```json +{ + "bpns": [ + { + "type": "manufacturerPartId", + "key": "12345678910", + "value": "bpn-123", + "resourceId": "1ca6f9b5-8e1d-422a-8541-9bb2cf5fe485" + } + ] +} +``` + +##### 2.1.4.3 Registration of the Digital Twin and the Submodels in the Digital Twin Registry + +A data provider **MUST** register their AAS of the product with the following values for the `idShort`: + +- for batteries: `Battery_{{PartInstanceId}}` +- for transmissions: `Transmission_{{PartInstanceId}}` + +For other product types the format `{{Product Name}}_{{PartInstanceId}}` **SHOULD** be used. + +Additionally, the AAS **MUST** be registered with `specificAssetIds: partInstanceId` and depending on the current lifecyclePhase of the product with + +- `assetLifecyclePhase = AsBuild` for product that already have been build or +- `assetLifecyclePhase = AsPlanned` for products not yet build. + +When describing `asPlanned` information, `ExternalReference` has to be set to `PUBLIC_READABLE` as described in the [Digital Twin Registry documentation](https://github.com/eclipse-tractusx/sldt-digital-twin-registry/tree/main/docs) + +In case the **OPTIONAL** `drill down functionality` is integrated in the application using the IRS [CX-0005](#211-list-of-standalone-standards), the digital twin **MUST** have a `globalAssetId` attribute with the Global Unique UUID of the asset. + +As described in the industry core standards [CX-0126](#211-list-of-standalone-standards) and [CX-0127](#211-list-of-standalone-standards), when digital twins **MUST** include the key `digitalTwinType`. When in **Instance Level** the value `PartInstance` **MUST** be used and in case of **Type Level** the value `PartType` **MUST** be used. + +**Example of a battery in as-planned lifecycle stage:** + +```json +{ + "idShort": "Battery_{{PartInstanceId}}", + "globalAssetId": "{{digitalTwinGlobalUniqueUUID}}", + "id": "{{digitalTwinId}}", + "specificAssetIds": [ + { + "name": "manufacturerId", + "value": "{{manufacturerId (BPNL)}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{BPN number of partner}}" + }, + { + "type": "GlobalReference", + "value": "PUBLIC_READABLE" + } + ] + } + }, + { + "name": "manufacturerPartId", + "value": "{{manufacturerPartId}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{BPN number of partner}}" + }, + { + "type": "GlobalReference", + "value": "PUBLIC_READABLE" + } + ] + } + }, + { + "name": "partInstanceId", + "value": "{{PartInstanceId}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{BPN of partner}}" + } + ] + } + }, + { + "key" : "assetLifecyclePhase", + "value": "AsPlanned" + }, + { + "key" : "digitalTwinType", + "value": "PartInstance" + } + ], + ... +} +``` + +Data provider **MUST** provide their product passport information in the `submodelDescriptors` depending on their product with the following information: + +| Product type | used data model | mandatory `idShort` | +| ---------------- | -------------------------- | -------------------- | +| Generic Passport | Digital Product Pass 4.0.0 | `digitalProductPass` | +| Batteries | BatteryPass v5.0.0 | `batteryPass` | +| Transmissions | Transmission Pass 2.0.0 | `transmissionPass` | + +- The data provider also **MUST** provide a API Endpoint following the [CX-0002](#211-list-of-standalone-standards). + Data- provider **MUST** register the related sub-models as shown in the example below. +- The id added to the `subprotocolBody` **SHOULD** be a UUIDv4. +- The `href` definition follows [CX-0002](#211-list-of-standalone-standards). + - After the negotiation and transfer of the `subprotocolBody` asset following [CX-0018](#211-list-of-standalone-standards) the the `href` EDR token from the EDC Data Plane Proxy will be used it **MUST** return the aspect model JSON payload. + +**Example of a transmission:** + +```json +"submodelDescriptors":[ + { + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "https://{{edc.data.plane}}/{{path}}/urn:uuid:777a3f0a-6d29-4fcd-81ea-1c27c1b870cc", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "{{AssetId_of_EDCAsset}};dspEndpoint=https://{{edc.control.plane}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ], + "idShort": "transmissionPass", + "id": "urn:uuid:777a3f0a-6d29-4fcd-81ea-1c27c1b870cc", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "Submodel", + "value": "urn:bamm:io.catenax.transmission.transmission_pass:2.0.0#TransmissionPass" + } + ] + }, + "description": [ + { + "language": "en", + "text": "Transmission Passport Submodel" + } + ], + { + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "https://{{edc.data.plane}}/{{path}}/urn:uuid:777a3f0a-6d29-4fcd-81ea-1c27c1b870cc", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "{{AssetId_of_EDCAsset}};dspEndpoint=https://{{edc.control.plane}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ], + "idShort": "digitalProductPass", + "id": "urn:uuid:777a3f0a-6d29-4fcd-81ea-1c27c1b870cc", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "Submodel", + "value": "urn:samm:io.catenax.generic.digital_product_passport:4.0.0#DigitalProductPassport" + } + ] + }, + "description": [ + { + "language": "en", + "text": "Digital Product Passport Submodel" + } + ] + } + } +] +``` + +## 3 ASPECT MODELS + +> *This section is normantive* + +### 3.1 ASPECT MODEL "DIGITAL PRODUCT PASSPORT" + +#### 3.1.1 INTRODUCTION + +The DPP includes data about components, materials and chemical substances, information on reparability, spare parts, environmental impact and professional disposal for a product. The corresponding data models describing such physical goods will be updated, as newer versions of relevant public regulations will be published. The main basis is provided by the document \"Proposal for a REGULATION OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL establishing a framework for setting ecodesign requirements for sustainable products and repealing Directive 2009/125/EC\" from March 30th, 2022. The latest version of the document was the provisional agreement between the EU Council and the Parliament from January 9th, 2024. The text is informal, but the content of the final regulation was agreed between these two institutions. +Due to the last update, the title of Ecodesign Regulation has been changed to: "Proposal for a REGULATION OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL establishing a framework for setting ecodesign requirements for sustainable products, amending Regulation (EU) 2023/1542 and repealing Directive 2009/125/EC". + +To use the model pieces of other models are imported. These have the following identifiers: + +- urn:samm:io.catenax.batch:3.0.0# +- urn:samm:io.catenax.shared.part_classification:1.0.0# +- urn:samm:io.catenax.part_type_information:1.0.0# +- urn:samm:io.catenax.shared.business_partner_number:2.0.0# +- urn:samm:io.catenax.serial_part:3.0.0# +- urn:samm:io.catenax.shared.quantity:2.0.0# +- urn:samm:io.catenax.shared.uuid:2.0.0# + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [CX-0003 SAMM Semantic Aspect Meta Model](https://catenax-ev.github.io/docs/standards/overview). + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to [CX-0003 SAMM Semantic Aspect Meta Model](https://catenax-ev.github.io/docs/standards/overview). + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. The license information is available in github. +In case of doubt the license, copyright and authors information in github overwrites the information in this specification document. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +This semantic model has the unique identifier: + +``` +urn:samm:io.catenax.generic.digital_product_passport:4.0.0# +``` + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the [SAMM command line interface](https://github.com/eclipse-esmf). + +##### 3.1.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. It can be found in the current version 4.0.0 in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.generic.digital_product_passport/4.0.0/DigitalProductPassport.ttl +``` + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". It can be found in the current version in the "gen" subfolder in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.generic.digital_product_passport/4.0.0/gen +``` + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. It can be found in the current version in the "gen" subfolder in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.generic.digital_product_passport/4.0.0/gen +``` + +### 3.2 ASPECT MODEL "BATTERY PASS" + +#### 3.2.1 INTRODUCTION + +The battery pass describes information collected during the lifecycle of a battery. The battery passport is implementing the requirements if the Regulation (EU) 2023/1542 of the European Parliament and of the Council of 12 July 2023 concerning batteries and waste batteries, amending Directive 2008/98/EC and Regulation (EU) 2019/1020 and repealing Directive 2006/66/EC. Additionally attributes come from the Proposal for Ecodesign for Sustainable Products Regulation (see [above](#311-introduction)). +To use the model pieces of the [Digital Product Passport](#31-aspect-model-digital-product-passport) model are imported by reference, reutilizing semantically identical parts of digital product passports from the generic data model. + +#### 3.2.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [CX-0003 SAMM Semantic Aspect Meta Model](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Archiv/Update_Juli_23_R_3.2/CX-0003-SAMMSemanticAspectMetaModel-v1.0.2.pdf). + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to [CX-0003 SAMM Semantic Aspect Meta Model](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Archiv/Update_Juli_23_R_3.2/CX-0003-SAMMSemanticAspectMetaModel-v1.0.2.pdf). + +#### 3.2.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. The license information is available in github. +In case of doubt the license, copyright and authors information in github overwrites the information in this specification document. + +#### 3.2.4 IDENTIFIER OF SEMANTIC MODEL + +This semantic model has the unique identifier: + +``` +urn:samm:io.catenax.battery.battery_pass:5.0.0# +``` + +#### 3.2.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the [SAMM command line interface](https://github.com/eclipse-esmf). + +##### 3.2.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. It can be found in the current version 5.0.0 in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.battery.battery_pass/5.0.0/BatteryPass.ttl +``` + +##### 3.2.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". It can be found in the current version in the "gen" subfolder in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.battery.battery_pass/5.0.0/gen +``` + +##### 3.2.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. It can be found in the current version in the "gen" subfolder in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.battery.battery_pass/5.0.0/gen +``` + +### 3.3 ASPECT MODEL "TRANSMISSION PASS" + +#### 3.3.1 INTRODUCTION + +The transmission passport corresponds to the [Digital Product Passport](#31-aspect-model-digital-product-passport) and its underlying regulation. By incorporating circularity parameters, the Transmission Passport aims to enhance transparency and promote a circular economy. It describes the data that is collected and available during the lifespan of a transmission. + +#### 3.3.2 SPECIFICATIONS ARTIFACTS + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [CX-0003 SAMM Semantic Aspect Meta Model](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Archiv/Update_Juli_23_R_3.2/CX-0003-SAMMSemanticAspectMetaModel-v1.0.2.pdf). + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub conformant to [CX-0003 SAMM Semantic Aspect Meta Model](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Archiv/Update_Juli_23_R_3.2/CX-0003-SAMMSemanticAspectMetaModel-v1.0.2.pdf). + +#### 3.3.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. The license information is available in github. +In case of doubt the license, copyright and authors information in github overwrites the information in this specification document. + +#### 3.3.4 IDENTIFIER OF SEMANTIC MODEL + +This semantic model has the unique identifier: + +``` +urn:samm:io.catenax.transmission.transmission_pass:2.0.0# +``` + +#### 3.3.5 FORMATS OF SEMANTIC MODEL + +All formats can be generated through the turtle file and the [SAMM command line interface](https://github.com/eclipse-esmf). + +##### 3.3.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. It can be found in the current version 2.0.0 in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.transmission.transmission_pass/2.0.0/TransmissionPass.ttl +``` + +##### 3.3.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation "GetSubmodel". It can be found in the current version in the "gen" subfolder in the github repository. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.transmission.transmission_pass/2.0.0/gen +``` + +##### 3.3.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification. + +``` +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.transmission.transmission_pass/2.0.0/gen +``` + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normantive* + +### 4.1 EDC DATA ASSET STRUCTURE + +The general asset structure **MUST** follow the [CX-0018](#211-list-of-standalone-standards). +Examples are in the official [Connector Kit](https://eclipse-tractusx.github.io/docs-kits/kits/Connector%20Kit/Adoption%20View/connector_kit_adoption_view). +The following subchapters define the specifics for this standard. + +#### 4.1.1 EDC Data Asset + +The EDC assets for product passports **MUST** follow the JSON. + +```json +{ + "@context": { + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "https://purl.org/dc/terms/" + }, + "@type": "Asset", + "@id": "{{assetId}}", + "properties": { + "type": { + "@id": "Asset" + }, + "name": "{{asset-name}}", + "description": "{{Description}}", + "contenttype": "{{type}}" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{submodel.server.endpoint}}", + "proxyQueryParams": "true", + "proxyPath": "true", + "proxyMethod": "true", + "proxyBody": "true" + } +} +``` + +#### 4.1.2 EDC Policy Structure + +A participant mentioned under [1.1](#11-audience--scope) **MUST** sign the overall +[Catena-X Terms and Condition](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations) as well as the sustainability agreement +[circular economy framework agreement](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations). + + Have a look at example policies [here](https://github.com/catenax-eV/cx-odrl-profile/blob/main/example_usage_policy.json). A guideline for different use cases profiles has been provided [here](https://github.com/catenax-eV/cx-odrl-profile/blob/main/profile.md) + +##### 4.1.2.1 Conventions for Use Case Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to: + +- the detailed [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +##### 4.1.2.2 Additional Details regarding Access Policies + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +##### 4.1.2.3 Additional Details regarding Usage Policies + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”), for the Digital Product Pass **MUST** be the latest circular economy framework agreement contraint provided in the profiles [here](https://github.com/catenax-eV/cx-odrl-profile/blob/main/profile.md#frameworkagreement). +- for the Digital Product Passport, Battery Passport and other passports the latest (“UsagePurpose”) for circular economy "dpp" **MUST** be used. It is defined [here](https://github.com/catenax-eV/cx-odrl-profile/blob/main/profile.md#usagepurpose) in the latest policy profile contraints. + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODLR policy rule values to be used for the above-mentioned types are provided via the [ODRL policy repository](https://github.com/catenax-eV/cx-odrl-profile). + +##### 4.1.3 Contract Definition + +Contract definitions of data providers **MUST** follow this structure (also defined in [CX-0018](#211-list-of-standalone-standards)): + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@id": "{{ContractDefinitionId}}", + "@type": "ContractDefinition", + "accessPolicyId": "{{AccessPolicyId}}", + "contractPolicyId": "{{ContractPolicyId}}", + "assetsSelector": { + "@type": "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "{{AssetId}}" + } +} +``` + +## 5 PROCESSES + +> *This section is normantive* + +Not applicable. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normantive* + +- See chapter [2.1.1](#211-list-of-standalone-standards). +- Public law references + - [Proposal for a REGULATION OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL concerning batteries and waste batteries, repealing Directive 2006/66/EC and amending Regulation (EU) No 2019/1020](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A52020PC0798) + - [Proposal for a REGULATION OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL establishing a framework for setting ecodesign requirements for sustainable products, amending Regulation (EU) 2023/1542 and repealing Directive 2009/125/EC](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:52022PC0142) - referenced as "ESPR". + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +No further references. + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +A reference implementation for data consumption according to the presented standard can be found at [https://github.com/eclipse-tractusx/digital-product-pass](https://github.com/eclipse-tractusx/digital-product-pass). + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0143-UseCaseCircularEconomyDigitalProductPassportStandard/assets/img/digitalProductPassContext.jpg b/docs/standards/CX-0143-UseCaseCircularEconomyDigitalProductPassportStandard/assets/img/digitalProductPassContext.jpg new file mode 100644 index 000000000..f75dfd3af Binary files /dev/null and b/docs/standards/CX-0143-UseCaseCircularEconomyDigitalProductPassportStandard/assets/img/digitalProductPassContext.jpg differ diff --git a/docs/standards/CX-0144-ESSUseCaseStandard/CX-0144-ESSUseCaseStandard.md b/docs/standards/CX-0144-ESSUseCaseStandard/CX-0144-ESSUseCaseStandard.md new file mode 100644 index 000000000..26c6b47e0 --- /dev/null +++ b/docs/standards/CX-0144-ESSUseCaseStandard/CX-0144-ESSUseCaseStandard.md @@ -0,0 +1,456 @@ +# CX-0144 ESS Use Case Standard 1.0.0 + +## ABSTRACT + +Catena-X aims to support supply chain due diligence obligations in a market environment that miss full up- and downstream transparency. This is argued to be relevant for Environmental and Social Standards (ESS) incident tracking, without compromising GAIA-X and Catena-X principles like data sovereignty, interoperability, standardization, and use of federated services. + +In case a violation against these laws occurs, an ESS incident can be created and transmitted to the Catena-X network. The Catena-X network and the ESS use case standard support the Catena-X members in this process. + +## FOR WHOM IS THE STANDARD DESIGNED + +This standard is applicable for: + +- Data Provider / Consumer +- Business Application Provider + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +The ESS incident aspect model, which was described in CX-0113, has been integrated into this document. + +## 1 INTRODUCTION + +The German Supply Chain Due Diligence Act came into force on January 1st, 2023. This law regulates corporate responsibility for compliance with human rights in global supply chains. These include, for example, protection against child labour, the right to fair wages and the protection of the environment. This legislation can be added to a long list of existing and future legislation that regulate our global supply chains, like the EU Corporate Sustainability Due Diligence Directive (CSDDD), the EU Ecodesign for Sustainable Products Regulation (ESPR), EU Corporate Sustainability Reporting Directive (CRSD), or the International Bill of Human Rights. Companies governed by environmental and social standards (ESS) would like to determine if they are affected by an incident reported in the global supply network. Consequently, they could prove to be fully compliant with legal requirements, including but not limited to the German Supply Chain Due Diligence Act. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following roles: + +- Data Provider / Consumer +- Business Application Provider + +This standard is relevant for the Business Domain Sustainability / use case ESS incident. Scope of this document is to provide guidance about the structure of the data model and the processes behind the ESS use case. + +Note: Fulfilling a use-case standard by a data provider / consumer can be done in two ways: A) Purchase a certified app for the use-case. +In this case the data provider / consumer does not need to proof conformity again and B) Data Provisioning / Consumption without a certified app for the use-case. +In this case the data provider / consumer needs to proof conformity with all single standards listed in this document. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +In order to effectively manage ESS incidents in the supply chain, a standardized approach to capturing and exchanging ESS incident data is essential. A standardized ESS Incident data model and common guidelines for the data exchange as defined in the Catena-X network provide a structured framework for collecting, organizing, and sharing ESS incident information across industries and stakeholders. Thus, the ESS use case standard supports collaboration and taking measures to ensure that the legal regulations are followed. + +To participate in the ESS use case, the following single standards mentioned in chapter REFERENCES MUST be fulfilled by all participants for which the standard is relevant. + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in BCP 14 \[RFC2119\] \[RFC8174\] when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove that they conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +### 1.4 EXAMPLES + +For examples please refer to [ESS KIT](https://eclipse-tractusx.github.io/docs-kits/category/ess-kit). + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +Business Partner Number (BPN): A BPN is the unique identifier of a partner within Catena-X with BPN-L, BPN- S, BPN-A + +ESS: Environmental and Social Standards ESS incident: An incident violating Environmental and / or Social Standards + +IRS: Recursive Item Relationship is a service that can be used to recursively trace a supply chain + +KA: Knowledge Agent is a standard to bring semantic web protocols into dataspaces + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normantive* + +### 2.1 ESS use case + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +The standards from other use cases that are applicable here, are listed in chapter NORMATIVE REFERENCES. + +#### 2.1.2 DATA REQUIRED + +The mandatory data described in the aspect model MUST be provided by data providers. The optional data described in the aspect model SHOULD be provided by data providers. The mandatory data MUST be consumed by the data consumers. The optional data SHOULD be consumed by the data consumers. + +Mandatory data MUST be managed by the Business Application Providers. Optional data SHOULD be managed by the Business Application Providers. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +The standards mentioned in chapter REFERENCES MUST be fulfilled by all participants for which the standard is relevant. + +### Conventions for Use Case Policy in context data exchange + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. A set of specific policies on data offering and data usage level detail the conditions under which data may be accessed, shared, and used, ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository. This document provides in-depth explanations of the terms and conditions applied to data access and utilization, ensuring that all engagement with our data is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. Those schemas MUST be followed when providing services or apps for data sharing/consuming. + +#### Additional Details regarding Access Policies + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, Data Provider maintains control over its anti-trust obligations when sharing certain data. In particular, Data Provider may apply Access Policies to restrict access to a particular data offer for only one Participant identified by a specific business partner number: + +- Membership +- BPNL + +#### Additional Details regarding Usage Policies + +In the context of data usage policies (“Usage Policies”), Participants and related services MUST use the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies MAY include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODLR policy rule values to be used for the above-mentioned types are provided via the ODRL policy repository. + +## 3 ASPECT MODELS + +> *This section is normantive* + +### 3.1 ASPECT MODEL "essIncident" + +#### 3.1.1 INTRODUCTION + +This chapter describes the semantic model essIncident used in the Catena-X network. + +see TABLES + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +see FORMATS OF SEMANTIC MODEL + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has a unique identifier. +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.essincident +version 3.0.0 + +urn:bamm:io.catenax.essincident:3.0.0 + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +All different formats of the semantic model can be found in the github repository. + +[https://github.com/eclipse-tractusx/sldt-semantic- models/tree/main/io.catenax.essincident/3.0.0](https://github.com/eclipse-tractusx/sldt-semantic-%20models/tree/main/io.catenax.essincident/3.0.0) + +##### 3.1.5.1 RDF TURTLE + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.essincident/3.0.0/EssIncident.ttl + +The open-source command line tool of the Eclipse Semantic Modeling Framework is used for generation of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template or a HTML documentation. + +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.essincident/3.0.0/gen + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload of the Asset Administration Shell for the API operation \"GetSubmodel\". + +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.essincident/3.0.0/gen/EssIncident-schema.json + +##### 3.1.5.3 AASX + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification conformant to \\ \[\[SMT\](#32-non-normative-references)\]. + +Note: As soon as the specification V3.0 of the Asset Administration Shell specification is available an update will be provided. + +https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.essincident/3.0.0/gen/EssIncident.aasx + +##### 3.1.5.4 JSON SAMPLE + +```JSON +{ + "flagAnonymous": false, + "incidentStatusInformation": "new", + "essIncidentIssuerLastName": "Testuser Last name", + "rawMaterial": "Natural Rubber", + "industry": "Extraction of raw materials", + "subCaseOpCoIds": "9f47b3c8-b6d4-44f1-99ba-6bdb33916cac, 9f47b3c8-b6d4-44f1-99ba-6bdb33916cad", + "incidentSubcategory": "Child labour", + "incidentSubject": "Child labour on rubber producer Farm A", + "essIncidentIssuerAddress": { + "locality": { + "value": "Mannheim", + "technicalKey": "BLOCK" + }, + "country": { + "shortName": "" + }, + "postCode": { + "value": "68161\\12", + "technicalKey": "CEDEX" + }, + "thoroughfare": { + "value": "Bernstra?e", + "number": "45", + "technicalKey": "STREET" + }, + "premise": { + "value": "Werk 1", + "technicalKey": "BUILDING" + }, + "postalDeliveryPoint": { + "value": "Tor 1", + "technicalKey": "INTERURBAN_DELIVERY_POINT" + } + }, + "essOriginatorCompanyName": "Rubbery Ltd.", + "essOriginatorCountrySubdivision": "BR-SP", + "productCommodity": "Tire", + "essOriginatorAddress": { + "locality": { + "value": "Mannheim", + "technicalKey": "BLOCK" + }, + "country": { + "shortName": "" + }, + "postCode": { + "value": "68161\\12", + "technicalKey": "CEDEX" + }, + "thoroughfare": { + "value": "Bernstra?e", + "number": "45", + "technicalKey": "STREET" + }, + "premise": { + "value": "Werk 1", + "technicalKey": "BUILDING" + }, + "postalDeliveryPoint": { + "value": "Tor 1", + "technicalKey": "INTERURBAN_DELIVERY_POINT" + } + }, + "incidentCategory": "Environmental", + "incidentAttachment": "telnet://192.0.2.16:80/", + "productDescription": "Natural Rubber", + "essOriginatorBpnA": "BPNA1234567890ZZ", + "essIncidentIssuerPhoneNo": "+49-123-456789", + "incidentExternalSubject": "Child labour on a rubber producer farm", + "incidentShareFlag": false, + "incidentExternalNotes": "Child labour at production site of a rubber producer in Brazil", + "essIncidentIssuerFirstName": "Testuser First name", + "essIncidentIssuerId": "9a47b3c8-b6d4-44f1-99ba-6bdb33916cac", + "masterOpCoId": "9f47b3c8-b6d4-44f1-99ba-6bdb33916cac", + "incidentSystemId": "123456789", + "essOriginatorBpnL": "BPNL1234567890ZZ", + "essOriginatorCoordinates": { + "longitude": "-79.517415", + "latitude": "-5.422077" + }, + "essIncidentIssuerCountrySubdivision": "IN-AP", + "essIncidentIssuerEmailAddress": "test@example.com", + "essOriginatorBpnS": "BPNS1234567890ZZ", + "systemDate": "2022-08-31T23:22:12Z", + "incidentDisplayId": "123456789101", + "incidentDate": "2022-08-31T00:00:00Z", + "incidentId": "9f47b3c8-b6d4-44f1-99ba-6bdb33916cac", + "incidentDescription": "Child labour at production site of the rubber producer Farm A in Brazil" +} +``` + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normantive* + +Not applicable as no implemented application available. + +## 5 PROCESSES + +> *This section is normantive* + +The ESS Incident management process is further described and illustrated in the [ESS KIT](https://eclipse-tractusx.github.io/docs-kits/category/ess-kit). + +![ESS Block Diagram](./assets/CX-0144-ESS-figure1.png) + +### 5.1 INTAKE APPLICATION - CLEARING AGENCY + +An incident has been reported to the Catena-X network. The incident can be reported manually e.g. by a whistleblower or automated by a Third Party InfoProvider. The unstructured information (text and/or pictures) about each incident will be collected along with country-, company-, material-related data if available. + +### 5.2 CLEARING AGENCY - CATENA-X SERVICES + +The Clearing Agency is prompted to clear incidents. This independent body has the tasks among others, to improve quality of data and reduce fraud or fakes. This includes but is not limited to, manual search and input from expert, consolidation of reports of the same incident and finally accept or archive incidents. + +The use case ESS is convinced that the most promising way to solve an ESS incident will be a bottom-up approach. Once the Clearing Agency found that the incident\'s originator (here called: L0) is a Catena-X member, the Clearing Agency can use Catena-X Services find out the BPN-L, BPN-S and the EDC endpoints of the incident originator. Then the ESS incident is transferred to the incident originator via the Catena-X network. + +In case no Catena-X member can be identified as incident originator, the clearing agency will maintain the corresponding status "no member found". + +If a Catena-X member wants to find out if a certain product is affected by an incident a top-down approach can be used. The Clearing Agency can initiate an occasion-related trace if a Catena-X member is affected by an ESS incident. To do so, the BPN-S of the incident originator and the product information, that shall be investigated, can be used to find out if a Catena-X member is affected or not. A spike has been implemented by recursive IRS to test this scenario. + +### 5.3 CATENA-X SERVICES - CLEARING AGENCY + +The Catena-X Services will return the requested information about the Catena-X incident originator. +In case no Catena-X member can be identified, this result will be returned to the Clearing Agency. + +### 5.4 CLEARING-AGENCY - CATENA-X MEMBER L0 + +The Clearing Agency addresses the Catena-X Member L0 via the Catena-X network and transfers all information that is available about the ESS incident. +The Clearing Agency must prepare and fill in the fields for external communication (anonymized data) for the data transfer to Catena-X Members LN. + +### 5.5 CATENA-X MEMBER L0 - CATENA-X TRACE APPLICATION + +The Catena-X Member L0 receives, hosts and investigates the ESS incident. The Catena-X Member L0 is responsible for defining appropriate measures about the ESS incident. + +To find affected Business Partners, Catena-X Member L0 can use Catena-X trace services like recursive IRS or Knowledge Agent. So, affected customers (respectively suppliers in case of a top-down approach) and their BPN-numbers and EDC endpoints can be identified. + +### 5.6 CATENA-X TRACE APPLICATION - CATENA-X MEMBER L0 + +Catena-X trace services like recursive IRS or Knowledge Agent will return the requested information about the Catena-X Business Partners. + +## 5.7 CATENA-X MEMBER L0 - CATENA-X MEMBER L1 + +Catena-X Member L0 will address Catena-X Member(s) L1 via the Catena-X network. + +L1 Business partners have a direct relationship with L0. As already supported in existing legislation, L1 Business partners will have access to the status of the ESS incident and full information about this incident. + +## 5.8 CATENA-X MEMBER L1 - C-X Member LN + +To find affected Business Partners, Catena-X Member L1 can use Catena-X trace services like recursive IRS or Knowledge Agent. So, affected customers for a bottom-up approach, respectively affected suppliers in case of a top-down approach, along with their BPN-numbers and EDC endpoints can be identified. + +Catena-X Members LN have an indirect relationship with the potential incident originator L0. They will receive anonymized incident information and relevant changes about the incident (anonymized data, incident category, incident subcategory, incident status etc.). + +In case of a bottom-up approach, the process moves from Business partner to Business partner up the supply chain with the incident originator as the starting point. +In case of a top-down approach, the process moves from Business partner to Business partner down the supply chain until the incident originator can be reached. + +### 5.9 CATENA-X Member L0 - CLEARING AGENCY + +As soon as the Catena-X member L0 has fulfilled his duties and defined measures about the ESS incident according to the agreed Code of Conduct, the incident can be closed. The Catena-X Member L0 reports to the Clearing Agency that the incident can be closed. + +The Clearing Agency sets the status to closed. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normantive* + +- CX-0001 EDC Discovery API 1.0.2 +- CX-0003 BAMM Aspect Meta Model 1.1.0 +- CX-0005 Item Relationship Service 2.0.0 +- CX-0006 Registration and initial onboarding 1.1.3 +- CX-0010 Business Partner Number 2.0.0 +- CX-0014 Employees and Technical Users 1.0.1 +- CX-0015 IAM & Access Control Paradigm 1.0.1 +- CX-0016 Company Attribute Verification 1.1.0 +- CX-0017 Company Role by the Connector 1.1.0 +- CX-0018 Eclipse Data Space Connector (EDC) 2.1.0 +- CX-0049 DID Document Schema 1.0.0 +- CX-0050 Framework Agreement Credential 1.0.0 +- CX-0053 BPN Discovery Services 1.0.1 +- CX-0067 Ontology models in Catena-X 1.0.0 +- CX-0084 Federated Queries in Data Spaces 1.0.0 + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +The principles and requirements described in the ESS - code of conduct shall be followed by all participants of the ESS use case. +Further information can be found in the [ESS KIT](https://eclipse-tractusx.github.io/docs-kits/category/ess-kit). + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Two spikes have been implemented for the tracing of an ESS incident: + +Recursive IRS - a spike has been implemented for a top-down approach (not preferred approach) in the kit: +[Traceability KIT | Eclipse Tractus-X (eclipse-tractusx.github.io)](https://eclipse-tractusx.github.io/docs-kits/category/traceability-kit) + +Knowledge Agent – has been implemented in a reference environment by the consortia for a bottom – up approach (preferred approach) using the kit: +[Agents Kit | Eclipse Tractus-X (eclipse-tractusx.github.io)](https://eclipse-tractusx.github.io/docs-kits/category/agents-kit) + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +![CX-0144-ESS_Figure1.png](./assets/CX-0144-ESS-figure1.png) + +### TABLES + +> *This section is non-normative* + +#### SEMANTIC MODEL + +##### Incident Information + +| **Attribute Name** | **Type** | **Description** | **Optional or Mandatory** | **Example** | +|--------------------|----------|-----------------|--------------------------|-------------| +| incidenCategory | String, value from list | Environmental and social standards related according to Supply Chain Due Diligence Act | M | Social | +| incidentSubcategory | String, value from list | Subcategory of an incident | M | Child labour | +| incidentSubject | String | Subject of an ESS incident | O | Child labour in country A on rubber producer "Farm A" | +| incidentExternalSubject | String | Replaces subject valid for external communication (anonymized data) | O | Child labour on rubber producer farm | +| incidentDescription | String | Full text description of an incident in the context of ESS | M | Small children under the age of 15 cleaning barrels with bare hands on rubber producer "Farm A" | +| incidentExternalNotes | String | Replaces description valid for external communication (anonymized data) | O | Small children under the age of 15 cleaning barrels with bare hands on rubber producer farm | +| incidentAttachment | URI | Picture(s) about the reported incident in the context of ESS (Environmental and Social Standards) | O | URL-link to picture | +| systemDate | DateTime | System created timestamp when the incident in the context of ESS (Environmental and Social Standards) was issued and saved | M | 2022-08-31T23:22:12Z | +| incidentDate | DateTime | Date and time information about the incident in the context of ESS (Environmental and Social Standards) | M | 2022-08-31T00:00:00Z | +| incidentId | UUIDv4 | Unique identifier for an incident in the context of ESS (Environmental and Social Standards) | M | 9f47b3c8-b6d4-44f1-99ba-6bdb33916cac | +| masterOpCoId | UUIDv4 | Incident ID that has been checked and validated. In case of duplicates the "parent" incident ID will be used as Master Operating Company ID | O | 9f47b3c8-b6d4-44f1-99ba-6bdb33916cac | +| subCaseOpCoIds | String | The related incidents that belong to a masterOpCoId, e.g. comma separated UUIDs | O | 9f47b3c8-b6d4-44f1-99ba-6bdb33916cac, 9f47b3c8-b6d4-44f1-99ba-6bdb33916cad | +| incidentStatusInformation | String, value from list | Status of incident progress, (default = new, in cleansing, in process, completed, closed) | M | new | +| incidentDisplayId | String | Human readable format of Incident ID | O | 123456789101 | +| incidentShareFlag | Bool | Flag, that can be set to true to request to publish the incident, default = false | M | false | +| incidentSystemId | String | SystemID that defines the system of origin | O | 123456789 | + +##### Product Information + +| **Attribute Name** | **Type** | **Description** | **Optional or Mandatory** | **Example** | +|--------------------|----------|-----------------|--------------------------|-------------| +| productCommodity | String | Free-text description for commodity of a product affected by an incident in the context of ESS (Environmental and Social Standards) | O | Rubber | +| productDescription | String | Description of product or component affected by an incident in the context of ESS (Environmental and Social Standards) | O | Natural Rubber | +| rawMaterial | String | Raw material that causes an incident in the context of ESS (Environmental and Social Standards) | O | Natural Rubber | +| industry | String, value from list | Industry/ Branch that causes the incident according to questionnaire BAFA: Extraction of raw materials, Manufacture of components/intermediates, Manufacture of final products, Distribution/Trade, Waste treatment/recycling, Services, Lending/financing/insurance, Other | O | Extraction of raw materials | + +##### Company Information + +| **Attribute Name** | **Type** | **Description** | **Optional or Mandatory** | **Example** | +|--------------------|----------|-----------------|--------------------------|-------------| +| essOriginatorCountrySubdivision | String | Region within a country to which an ESS incident belongs | O | BR-SP | +| essOriginatorCoordinates | String | Longitude and Latitude that define exact geographic position of an incident in the context of ESS (Environmental and Social Standards) respectively GPS data | O | Latitude: -5.422077; Longitude: -79.517415 | +| essOriginatorCompanyName | String | Name of a company / an organisation that is the originator of an incident in the context of ESS (Environmental and Social Standards) | O | Rubbery Ltd. | +| essOriginatorAddress | String | Address of ESS originator (street, zip code, city) | O | Mainroad 1, 73230 Model City | +| essOriginatorBpnL | String | BPN-L of the company that causes the incident | O | BPNL1234567890ZZ | +| essOriginatorBpnS | String | BPN-S of the company that causes the incident | O | BPNS1234567890ZZ | +| essOriginatorBpnA | String | BPN-A of the company that causes the incident | O | BPNA1234567890ZZ | + +##### ESS Contact Information + +| **Attribute Name** | **Type** | **Description** | **Optional or Mandatory** | **Example** | +|--------------------|----------|-----------------|--------------------------|-------------| +| essIncidentIssuerFirstName | String | First name of ESS incident issuer | O | Testuser First name | +| essIncidentIssuerLastName | String | Last name of ESS incident issuer | O | Testuser Last name | +| essIncidentIssuerEmailAddress | String | Mail address of ESS incident issuer | O | test@example.com | +| essIncidentIssuerPhoneNo | String | Phone number of ESS incident issuer | O | +49-123-456789 | +| essIncidentIssuerAddress | String | Address of ESS incident issuer | O | XYZ-Road 73230 Model City | +| essIncidentIssuerCountrySubdivision | String | Region within a country to which an ESS incident issuer | O | IN-AP | +| essIncidentIssuerId | UUIDv4 | System generated unique identifier of incident issuer | M | 9a47b3c8-b6d4-44f1-99ba-6bdb33916cac | +| flagAnonymous | Bool | Flag that indicates if the ESS incident issuer wants to be anonymous | M | false | + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0144-ESSUseCaseStandard/assets/CX-0144-ESS-figure1.png b/docs/standards/CX-0144-ESSUseCaseStandard/assets/CX-0144-ESS-figure1.png new file mode 100644 index 000000000..99d5c5d29 Binary files /dev/null and b/docs/standards/CX-0144-ESSUseCaseStandard/assets/CX-0144-ESS-figure1.png differ diff --git a/docs/standards/CX-0145-DaysofsupplyExchange/CX-0145-DaysofsupplyExchange.md b/docs/standards/CX-0145-DaysofsupplyExchange/CX-0145-DaysofsupplyExchange.md new file mode 100644 index 000000000..a6073c7a1 --- /dev/null +++ b/docs/standards/CX-0145-DaysofsupplyExchange/CX-0145-DaysofsupplyExchange.md @@ -0,0 +1,1319 @@ +# CX-0145 Days of supply Exchange 1.0.0 + +## ABSTRACT + +*Days of Supply (DoS)* in logistics is a critical metric used to estimate how long current inventory +levels will last under normal consumption patterns. This calculation is essential in supply chain +management as it assists in forecasting when stock replenishment is needed, thereby preventing stock +shortages or overstocking. It plays a significant role in ensuring efficient inventory turnover, +maintaining a balance between having enough stock to meet demand and avoiding excess inventory that +ties up capital. + +To effectively address the challenges associated with manual calculation and estimation of *Days of Supply*, the standardization and interoperable exchange of this data among Catena-X business +partners is essential. Establishing a standardized semantic definition to describe *Days of Supply* and a common API is a fundamental step to enable this exchange and foster compatibility. This +approach maximizes the range of solutions available to mitigate potential supply shortages and +supports precise inventory planning. + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +This is the first version of the standard. + +## 1 INTRODUCTION + +In the intricate frameworks of supply chain management and manufacturing, the *Days of Supply* metric emerges as a critical tool for optimizing inventory levels and ensuring effective planning. +It measures how long the current inventory will suffice to meet future demands under the assumption +that no additional inventory is received. This key figure, calculated in days, is essential for +maintaining efficient inventory turnover and preventing both shortages and excesses that can impact +business operations. + +Effective monitoring and calculation of *Days of Supply* are paramount for businesses to anticipate +and mitigate potential inventory imbalances. However, accurately capturing and analyzing this data +poses a significant challenge, as conventional methods and systems may not offer comprehensive +support for this nuanced metric. + +The necessity for a standardized and semantically precise definition of *Days of Supply* cannot be +overstated. By establishing clear standards for this metric, supply chain participants can ensure +interoperable data exchange, enhancing collaboration and operational efficiency across the board. +This initiative not only aids in avoiding inventory-related issues but also contributes to more +streamlined and responsive supply chain operations. + +The initiative towards standardizing *Days of Supply* is aimed at providing businesses with the +tools they need for more effective inventory and production planning, enabling them to improve +process efficiency, minimize risks of inventory mismatches, and bolster overall supply chain +resilience. + +*Days of Supply* can be applied in various use cases in logistics and supply chain management: + +1. **Manufacturing Sector** : Manufacturers rely on it to maintain adequate levels of raw materials + and components, ensuring uninterrupted production lines. +2. **Retail Industry** : Retailers use it to manage inventory levels of fast-moving consumer goods. + They can predict when they need to reorder items to avoid stockouts, especially during peak + shopping seasons. +3. **Healthcare and Pharmaceuticals** : It's crucial for managing the inventory of medicines and + medical supplies, particularly those with short shelf lives or critical to patient care. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is relevant for the following roles defined in [[CX-OMW]](#62-non-normative-references): + +- **Data Providers** willing to provide *Days of Supply* data +- **Data Consumers** interested in requesting and receiving *Days of Supply* data +- **Business Application Providers** interested in providing solutions implementing this standard +- **Consulting Services Providers** interested in supporting companies fulfilling the standard + +The scope of this standard is only the *Days of Supply* aspect model and the corresponding API usage. +It describes the exchange of *Days of Supply* data through a connector compliant with [[CX-0018]](#61-normative-references). + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +In a typical item manufacturing and procurement process, a company determines the need to maintain +stock levels to meet demand. As part of this process, *Days of Supply* typically refers to metrics +or details about how long the existing inventory will last to satisfy current demand without +additional delivery or production. It includes calculations on the number of days the current +inventory is expected to meet demand based on average daily consumption. This metric provides key +insights into inventory efficiency and assists in planning reorders to ensure continuous operation +and is crucial for maintaining efficient inventory management and ensuring a smooth supply chain. + +Within the framework of the Catena-X network, this standard defines the *DaysOfSupply* aspect model. +Its purpose is to establish a consistent and uniform interpretation and handling of *Days of Supply* +among all interested parties, ensuring that this data is understood and managed in the same manner +by all stakeholders. + +*Figure 1* shows the high-level architecture of the *Days of Supply* exchange in the Catena-X +dataspace and the services that are involved. Both the data provider and the data consumer must be +members of the Catena-X network in order to communicate with each other. With the help of +Credential Service and the Identity Access Management (IAM) each participant can authenticate +itself, verify the identity of the requesting party and decide whether to authorize the request. The +*Days of Supply* data is provisioned in accordance with [[CX-0002]](#61-normative-references). + +![Figure 1: High-level architecture of the Days of Supply in the Catena-X](./assets/figure_1.svg) +*Figure 1: High-level architecture of the Days of Supply in the Catena-X* + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +The sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in +this specification are non-normative. Everything else in this specification is normative. The key +words **MAY** , **MUST** , **MUST NOT** , **OPTIONAL** , **RECOMMENDED** , **REQUIRED** , +**SHOULD** and **SHOULD NOT** in this document are to be interpreted as described in [BCP 14] +[[RFC2119]](#62-non-normative-references) [[RFC8174]](#62-non-normative-references) when, and only when, they appear in all capitals, as shown here. + +All participants and their solutions will need to prove that they are conform with the Catena-X +standards. To validate that the standards are applied correctly, Catena-X employs Conformity +Assessment Bodies (CABs). The proof of conformity for a single semantic model is done according to +the general rules for proving the conformity of data provided to a semantic model or the ability to +consume the corresponding data. Furthermore participants agree to follow the normative language of +this standardization document and to implement the required API-Endpoints described in [Chapter 4](#4-application-programming-interfaces). + +### 1.4 EXAMPLES + +The following JSONs provide an example of the value-only serialization of the "*Days Of Supply*" +aspect model for Days of Supply for one (see example one) and multiple days of supply (see example +too). + +Value-only JSON serialization of the with present day values of days of supply - "DoS for one day only". + +```json +{ + "materialGlobalAssetId": "urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df", + "allocatedDaysOfSupply": [ + { + "stockLocationBPNA": "BPNA1234567890ZZ", + "lastUpdatedOnDateTime": "2023-04-28T14:23:00.123456+14:00", + "amountOfAllocatedDaysOfSupply": [ + { + "date": "2024-01-01T14:23:00+01:00", + "daysOfSupply": 3.51 + } + ], + "stockLocationBPNS": "BPNS1234567890ZZ" + } + ], + "direction": "INBOUND" +} +``` + +Value-only JSON serialization of the with present day and two additional consecutive dates paired with +days of supply values - "DoS for multiple days". + +```json +{ + "materialGlobalAssetId": "urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df", + "allocatedDaysOfSupply": [ + { + "stockLocationBPNA": "BPNA1234567890ZZ", + "lastUpdatedOnDateTime": "2023-04-28T14:23:00.123456+14:00", + "amountOfAllocatedDaysOfSupply": [ + { + "date": "2024-02-01T14:23:00+01:00", + "daysOfSupply": 3.51 + }, + { + "date": "2024-02-02T14:23:00+01:00", + "daysOfSupply": 4.25 + }, + { + "date": "2024-02-03T14:23:00+01:00", + "daysOfSupply": 2.78 + } + ], + "stockLocationBPNS": "BPNS1234567890ZZ" + } + ], + "direction": "INBOUND" +} +``` + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +| **Name** | **Abrev.** | **Description** | +| --- | --- | --- | +| **Business Partner Number** | BPN | A BPN is the unique identifier of a partner within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Business Partner Number Site** | BPNS | A BPNS is the unique identifier of a partner site within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Business Partner Number Address** | BPNA | A BPNA is the unique identifier of a partner address within Catena-X as defined in [[CX-0010]](#61-normative-references). | +| **Direction** | / | Direction of the stock from data provider perspective. | +| **Date** | / | Date refers to the specific calendar day (current or projected) associated with the measured (or expected) inventory level. It serves as a timestamp for calculating Days of Supply, indicating when the inventory count was taken or projected. | +| **Days of Supply** | DoS | Amount of days, before the current stock is expected to be exhausted.

    Days of supply of a customer:

    Number of days where;
    (Stock) - Σ(daily Demand) >= 0

    Days of supply of a supplier:

    Number of days where;
    (Stock) - Σ(daily Outgoing Shipments) >= 0 | +| **Allocated Days of Supply** | / | Defines the number of days with allocated supply for an item stock in a given location that is available for the use in production or deliveries. The allocated days of supply are not available for other customers. | +| **Digital Twin** | DT | Digital representation of an asset that provides data on aspects of the represented data following [[CX-0002]](#61-normative-references). | +| **decentralized Digital Twin Registry** | dDTR | Component providing registration and discovery API implementations following [[CX-0002]](#61-normative-references). Sometimes referred to without the "decentralized" BUT in Catena-X those are always decentralized. | +| **Asset Administration Shell** | AAS | Technical concept for Digital Twins consisting of different standards. Application in Catena-X is described in Digital Twins in Catena-X standard ([[CX-0002]](#61-normative-references)) | +| **Shell Descriptor** | | Technical concept of the AAS API describing metadata of an Asset Administration Shell representing a Digital Twin. It holds identification information and metadata about which submodels are available and where to get the data from (see [[CX-0002]](#61-normative-references), [[IDTA-01002-3-0]](#62-non-normative-references)). There may exist multiple Shell Descriptor for the same represented Asset (see [[CX-0126]](#61-normative-references)). | +| **Submodel Descriptor** | | Technical concept of the AAS API describing metadata of Submodels within a Shell Descriptor (Asset Administration Shell) (see [[CX-0002]](#61-normative-references), [[IDTA-01002-3-0]](#62-non-normative-references)). | +| **Specific Asset Ids** | | Identifiers of the Shell Descriptor (Asset Administration Shell) that refer to common identification data for an asset/material at hand e.g., manufacturer part Id. Common specific asset ids used for identification are described in Industry Core Part Type Standard (see [[CX-0126]](#61-normative-references)). | +| **Asset Administration Shell Identifier** | AAS ID | Also referred to as Shell Descriptor id, is the technical identifier of the Shell Descriptor. | +| **Global Asset Id** | | Also referred to as Catena-X Id, is the Catena-X identifier for assets represented by Digital Twins (see [[CX-0126]](#61-normative-references)). | +| **Aspect** | | A domain-specific view on information and functionality associated with a specific Digital Twin with a reference to a concrete Aspect Model (see [[CX-0002]](#61-normative-references)). Within Catena-X, an aspect is formally described using the Semantic Aspect Meta Model (see [[CX-0003]](#61-normative-references)). | +| **Semantic Id** | | Identifier including namespace to specify the semantic description of submodels using the Semantic Aspect Meta Model (SAMM). It allows partners to know the exact data format and semantics when e.g., browsing catalogs (see [[CX-0003]](#61-normative-references)). | +| **Data Space Protocol** | DSP | A set of specifications designed to facilitate interoperable data sharing between entities governed by usage control and based on Web technologies. These specifications define the schemas and protocols required for entities to publish data, negotiate Agreements, and access data as part of a Dataspace. It is governed by the International Data Spaces Association. Connectors compliant to [[CX-0018]](#61-normative-references) support the Data Space Protocol. | +| **Shared Asset Approach** | | Digital twin pattern in which each party has a twin for the same asset (Part Type). They share the same identification data in terms of specific asset ids and global asset id. The digital twins do have different technical identifiers. | + +*Table 1: Terminology Days of Supply Exchange Standard* + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 "DAYS OF SUPPLY" + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0001]](#61-normative-references) | EDC Discovery API | 1.0.2 | +| [[CX-0002]](#61-normative-references) | Digital Twins in Catena-X | 2.2.0 | +| [[CX-0003]](#61-normative-references) | SAMM Aspect Meta Model | 1.1.0 | +| [[CX-0006]](#61-normative-references) | Registration and initial onboarding | 2.0.0 | +| [[CX-0010]](#61-normative-references) | Business Partner Number (BPN) | 2.0.0 | +| [[CX-0018]](#61-normative-references) | Dataspace Connectivity | 3.0.0 | +| [[CX-0126]](#61-normative-references) | Industry Core Part Type | 2.0.0 | + +*Table 2: List of mandatory standards* + +The usage of this standard may be complemented with the following Catena-X standards to further extend +the range of shortage prevention possibilities: + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0118]](#61-normative-references) | Delivery Information Exchange | 2.0.0 | +| [[CX-0120]](#61-normative-references) | Short-term Material Demand Exchange | 2.0.0 | +| [[CX-0121]](#61-normative-references) | Planned Production Output Exchange | 2.0.0 | +| [[CX-0122]](#61-normative-references) | Item Stock Exchange | 2.0.0 | +| [[CX-0146]](#61-normative-references) | Supply Chain Disruption Notifications | 1.0.0 | + +*Table 3: List of* *non-mandatory* *complementary standards* + +#### 2.1.2 DATA REQUIRED + +No additional data requirements. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### CONVENTIONS FOR USE CASE POLICY IN CONTEXT DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization +of data within the Catena-X use cases has been outlined. A set of specific policies on data offering +and data usage level detail the conditions under which data may be accessed, shared, and used, +ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data +usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository [[CX-ODRL]](#62-non-normative-references). This document provides in-depth explanations of the + terms and conditions applied to data access and utilization, ensuring that all engagement with our data + is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. + Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +###### ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for +members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, +Data Provider maintains control over its anti-trust obligations when sharing certain data. In +particular, Data Provider may apply Access Policies to restrict access to a particular data offer +for only one Participant identified by a specific business partner number. + +- Membership +- BPNL + +###### ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use +the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are +provided via the ODRL policy repository [[CX-ODRL]](#62-non-normative-references). + +##### REMINDER OF ANTITRUST + +Notice and/or acknowledgement concepts to raise awareness of antitrust issues during use of this standard +are **RECOMMENDED**, for example through the implementation of a help desk or pop-up info. + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +This standard builds upon the Industry Core Part Type [[CX-0126]](#61-normative-references) and the Digital Twins in +Catena-X [[CX-0002]](#61-normative-references) standards. It follows the following design patterns: + +- Usage of Digital Twins as shared assets to follow a pull approach for data. +- Usage of the specific asset IDs and further identification data for the Digital Twin for the Part Type + (see [[CX-0126]](#61-normative-references)). +- Provisioning of the *PartTypeInformation* on supplier side (see [[CX-0126]](#61-normative-references)). + +Because both parties may provide data regarding different aspects of the same Part Type Twin, they need +to use the same identification data to pinpoint it. + +- The supplier of the part has a Digital Twin representation and is then able to offer + *Days of Supply* data to customers. +- The customer, who orders or uses the part, has a Digital Twin representation to offer + *Days of Supply* data to a supplier. +- Both twins refer to the same asset and provide complementary information. They share the same + identification data in two partners' context. + - The supplier + - **MUST** create the Digital Twin first. + - **MUST** generate the Catena-X ID and ensure that the customer-specific asset IDs and submodel + descriptors are only accessible by the specific customer. + - **MAY** use the Digital Twin for multiple customers. + - The customer + - **MUST** create one Digital Twin per supplier. + - **MUST** use the Catena-X ID generated by the supplier. + +The definition of identification data (Catena-X ID, Asset Administration Shell ID, specific asset ID) +**MUST** follow the Industry Core Part Type [[CX-0126]](#61-normative-references). Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for further details. + +>***Note:*** The Part Type Twin's data is considered sensitive. Data providers **MUST** implement appropriate +measures ensuring that competitors-specific asset IDs and/or information about submodels is accessible +only to the data consumers it concerns, but not to their competitors. + +Figure 2 shows how the shared asset approach is realized. The orange lines show which submodels belong +to the respective AAS. All *Days of Supply* specific submodels are bound to the specific +Part Type's context e.g., meaning that the *Days of Supply* aspect is described for the specific +catalog item on supplier and customer side represented by the AASs. The orange submodels are the +submodels used within this standard's context. The grey submodels are used within the Industry Core +[[CX-0126]](#61-normative-references)(*PartTypeInformation, SingleLevelBomAsPlanned, SingleLevelUsageAsPlanned*). +The blue dashed lines show the references between DTs based on Catena-X UUIDs and BPNL information that +may be resolved by the Item Relationship Service (see [[CX-0126]](#61-normative-references)). + +![Figure 2: Conceptual levels of provisioning digital twins in the shared asset approach.](./assets/figure_2.svg) +*Figure 2: Conceptual levels of provisioning digital twins in the shared asset approach.* + +Figure 2 details two conceptual levels: + +- The Asset level contains the asset (Industry Core Part Type) represented by a Digital Twin. + The latter is provisioned as an Asset Administration Shell (AAS) within the decentralized Digital + Twin Registry (dDTR) of the data provider (supplier or customer). +- The Submodel level represents the actual information that are held by a Digital Twin (DT). Those + submodels follow the respective definition of the in Semantic Aspect Meta Model (SAMM) format + (see [Chapter 3](#3-aspect-models)). The dDTR only holds metadata about the Submodel + (e.g. kind of submodel via semantic ID or connector endpoint information). + +## 3 ASPECT MODELS + +> *This section is normative* + +### 3.1 "DAYS OF SUPPLY" ASPECT MODEL + +#### 3.1.1 INTRODUCTION + +This section describes the *Days Of Supply* semantic model used in the Catena-X network. For the complete +semantics and detailed description of its properties refer to the SAMM model in [Chapter 3.1.5.1](#3151-rdf-turtle). + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the +"semantic-driven workflow" to create a submodel template specification [[SMT]](#62-non-normative-references). + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [[CX-0003]](#61-normative-references) as +input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to [[CX-0003]](#61-normative-references). + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +> `urn:samm:io.catenax.days_of_supply:2.0.0` + +This identifier **MUST** be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The RDF turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional +file formats and serializations. It can be found under the following link: + +> [https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.days_of_supply/2.0.0/DaysOfSupply.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.days_of_supply/2.0.0/DaysOfSupply.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of +other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template +or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload +of the Asset Administration Shell for the API operation *"GetSubmodel"*. + +##### 3.1.5.3 AASX + +An AASX file **MUST** be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to [[SMT]](#62-non-normative-references). + +## 4 APPLICATION PROGRAMMING INTERFACES + +### 4.1 API USED TO EXCHANGE "DAYS OF SUPPLY" INFORMATION + +As described in [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids) this standard builds upon the [[CX-0002]](#61-normative-references) Digital Twins in Catena-X +and [[CX-0126]](#61-normative-references) Industry Core Part Type standards. Therefore, the APIs provided by the Digital Twin +standard are combined with the part identification defined in the Industry Core standard. This chapter +defines how the aforementioned standards and the [[CX-0018]](#61-normative-references) +standard **MUST** be used to facilitate the provisioning of *Days of Supply* data. The +usage of the Discovery Services defined in [[CX-0001]](#61-normative-references), [[CX-0053]](#61-normative-references) is not mandatory, +because this standard assumes an already existing business relationship between the involved parties. + +The sequence diagram in *Figure 3* provides an overview of the interactions required to register the +Part Type Twin following the shared asset approach. + +- Steps 1 & 2: Register the dDTR access for the partner at the connector +- Steps 3 & 4: When using the repository pattern, create the submodel (and twin) +- Steps 5 & 6: Register the submodel endpoint for the partner at the connector +- Steps 7 & 8: Register or update the twin Shell Descriptor relying on the registered Connector asset + for the submodel endpoint and the identification data of the partners. + +>***Note:*** This sequence diagram is simplified and does not cover the generation of the Part Type Twin +on supplier side and the handling of the identification data needed. Both partners need to create a +Part Type Twin of the shared asset as well as provide *Days of Supply* data. + +![Figure 3: Flow to create and register a digital twin](./assets/figure_3.svg) +*Figure 3: Flow to create and register a digital twin* + +The sequence diagram in Figure 4 provides an overview of the interactions required when a customer +(acting as data provider) provisions *Days of Supply* data to a supplier (acting as data consumer). + +The flow "*Supplier reads (updated) Submodel from Customer*" visualizes the sequence of calls when consuming data: + +- Steps 3 - 8: Contract dDTR usage in the connector. +- Steps 9 - 12: Lookup the Industry Core Part Type Twin for a Part Type based on the common identification data. +- Steps 13 - 18: Read the Shell Descriptor of the Industry Core Part Type Twin to extract the *Days of Supply* + submodel endpoint (registered at the connector). +- Steps 19 - 24: Contract the *Days of Supply* data usage in the connector. +- Steps 25 - 29: Consume and use the *Days of Supply* data. + +![Figure 4: Flow to lookup a digital twin and get a submodel.](./assets/figure_4.svg) +*Figure 4: Flow to lookup a digital twin and get a submodel.* + +>***Note:*** Depending on the use of repository patterns and the design of the Digital Twins, the data +may be updated manually in the Submodel endpoint. + +#### 4.1.1 CONNECTOR DATA ASSET STRUCTURE + +The endpoints for the dDTR and the Submodel Endpoint **MUST** be made available BUT they **MUST NOT** +be directly called data consumer. Rather, for access to dDTRs and Submodels, there **MUST** be contracts +negotiated in accordance with the DSP. Therefore, the endpoints **MUST** be offered as connector data +assets. To make these assets easily identifiable in the connector's catalog, each asset **MUST** be +configured with a set of properties as described in the corresponding sections below. + +The following table provides an overview of the connector data assets that the parties **MUST** offer +to be able to provision and/or consume *Days of Supply* data. + +| **Party** | **REQUIRED** | **Asset** | **Purpose** | +| --- | --- | --- | --- | +| Provider | Yes | "Digital Twin Registry" | Allows a consumer to query for Part Type Twins and their *Days of Supply* submodels. | +| Provider | Yes | "Submodel Days of Supply" | Allows a consumer to read actual *Days of Supply* information related to a Part Type Twin. | +| Consumer | Yes | "Digital Twin Registry" | Allows a consumer to query for Part Type Twins and their *Days of Supply* submodels. | +| Consumer | Yes | "Submodel Days of Supply" | Allows a consumer to read actual *Days of Supply* information related to a Part Type Twin. | + +*Table 4: Connector data assets* + +In the sections below the asset definitions of the two different kinds of assets are defined. + +##### CONNECTOR DATA ASSET STRUCTURE FOR "Digital Twin Registry" + +To allow partners to find the "Days of Supply" data for a specific Industry Core Part Type Twin, +the provider **MUST** register a connector data asset (see details in [[CX-0018]](#61-normative-references)) specifying the address +of the Digital Twin Registry of the provider (see [[CX-0002]](#61-normative-references)). + +The data asset **MUST** be configured with the set of properties as defined in the table below. + +| **Object** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***@id*** | Identifier of the asset | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. | +| properties | [**http://purl.org/dc/terms/type**](http://purl.org/dc/terms/type) | Defines the "Digital Twin Registry" according to the Catena-X taxonomy. | **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#DigitalTwinRegistry"}` to allow filtering the data assets catalog for the respective "Digital Twin Registry". | +| properties | [**https://w3id.org/catenax/ontology/common#version**](https://w3id.org/catenax/ontology/common#version) | The version of the standard defining the implemented API of the "Digital Twin Registry" | **MUST** correspond to the version of the standard defining the Interfaces of the "Digital Twin Registry". The value **MUST** be set to `"3.0"` for "Digital Twin Registries" used by this standard. | +| dataAddress | **@type** | Type of the DataAddress node. | **MUST** be set to `"DataAddress"`. | +| dataAddress | ***baseUrl*** | Defines the HTTPS endpoint of the corresponding "Digital Twin Registry Endpoint". | The `{{ DIGITAL_TWIN_REGISTRY_ENDPOINT }}` refers to an URL under which the API of the "Digital Twin Registry" endpoint is available. HTTPS transport protocol **MUST** be used. | +| dataAddress | ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body | **SHOULD** be set to `"false"` to not allow the API endpoint to receive a HTTPS body via the HTTPS request. | +| dataAddress | ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method | **SHOULD** be set to `"false"` to only allow the API endpoint to receive GET requests. | +| dataAddress | ***proxyPath*** | Defines whether the endpoint allows to proxy paths for the URL | **MUST** be set to `"true"` to allow the API endpoint to receive appended paths of the HTTPS request. | +| dataAddress | ***type*** | Defines the type of data plane extension handling the data exchange | **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. | + +*Table 5: Connector data assets request properties* + +Additionally security identification information **MAY** be added to secure the "Decentralized Digital Twin Registry". + +When searching the Catalog of a provider, a consumer **SHOULD** use the following properties AND +their values to identify the Data Asset specifying "Digital Twin Registry". In the connector Data Asset +descriptions the API version valid for this standard is mentioned for the property +[`https://w3id.org/catenax/ontology/common#version`](https://w3id.org/catenax/ontology/common#version). The requester of a Data Asset **MUST** be +able to handle multiple Data Asset for this endpoint, being differentiated only by the version. +The requester **SHOULD** choose the Data Asset set with the highest compatible version number implemented +by themselves. If the requester cannot find a compatible version with their own, the requester **MUST** +terminate the data transfer. + +| **Property** | **Value** | +| --- | --- | +| http://purl.org/dc/terms/type | `{"@id": "https://w3id.org/catenax/taxonomy#DigitalTwinRegistry"}` | + +*Table 6: Connector data assets request properties values.* + +An example connector data asset definition is given below. + +>**Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "http://purl.org/dc/terms/" + }, + "@id": "{{CONNECTOR_ASSET_ID}}", + "properties": { + "dct:type": {"@id": "cx-taxo:DigitalTwinRegistry"}, + "cx-common:version": "3.0" + }, + "privateProperties": { + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ DIGITAL_TWIN_REGISTRY_ENDPOINT }}", + "proxyQueryParams": "true", + "proxyBody": "false", + "proxyPath": "true", + "proxyMethod": "false", + } +} +``` + +##### CONNECTOR DATA ASSET STRUCTURE FOR "Submodel" + +To allow partners to receive the "Days of Supply" data as defined in [Chapter 3](#3-aspect-models), +the provider **MUST** register a connector data asset (see details in[[ CX-0018]](#61-normative-references)) specifying the +address of the submodel endpoint (see [[CX-0002]](#61-normative-references)) providing the actual data. + +The data asset **MUST** be configured with the set of properties as defined in the table below. + +| **Object** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***@id*** | Identifier of the asset | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. | +| properties | [**http://purl.org/dc/terms/type**](https://purl.org/dc/terms/type) | Defines the "Submodel API" according to the Catena-X taxonomy. | **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#Submodel"}` to allow filtering the data assets catalog for the respective "Submodel API". | +| properties | [**https://admin-shell.io/aas/3/0/HasSemantics/semanticId**](https://admin-shell.io/aas/3/0/HasSemantics/semanticId) | The semantic identifier of the "Days of Supply" SAMM. | **MUST** be set to `{"@id": "urn:samm:io.catenax.days_of_supply:2.0.0#DaysOfSupply"}` to externally define how the Submodel must be interpreted. **MUST NOT** be set, if different submodels may be returned by this API. | +| properties | [**https://w3id.org/catenax/ontology/common#version**](https://w3id.org/catenax/ontology/common#version) | Version of the Submodel Interface Specification | **MUST** be set to `"3.0"` in accordance to [[CX-0002]](#61-normative-references). | +| dataAddress | **@type** | Type of the DataAddress node. | **MUST** be set to `"DataAddress"`. | +| dataAddress | ***baseUrl*** | Defines the HTTPS Submodel endpoint provisioning the *Days of Supply* data | The `{{ SUBMODEL_ENDPOINT }}` refers to an URL under which the Submodel API Endpoint ([[CX-0002]](#61-normative-references)) is available to provide the "Days of Supply" . HTTPS transport protocol **MUST** be used. | +| dataAddress | ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body | **SHOULD** be set to `"false"` to not allow the API endpoint to receive a HTTPS body via the HTTPS request. | +| dataAddress | ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method | **SHOULD** be set to `"false"` to only allow the API endpoint to receive GET requests. | +| dataAddress | ***proxyPath*** | Defines whether the endpoint allows to proxy paths for the URL | **MUST** be set to `"true"` to allow the API endpoint to receive appended paths of the HTTPS request. Setting this parameter depends on the implementation of the submodel lookup. | +| dataAddress | ***type*** | Defines the type of data plane extension handling the data exchange | **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. | + +*Table 7: Connector data assets request properties* + +Additionally security identification information **MAY** be added to secure the "Submodel API". + +When searching the data assets catalog of a provider, a consumer **SHOULD** use the `assetId` previously +determined via `subprotocolBody` of the SubmodelDescriptor's endpoint definition of subprotocol type "DSP". +Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for the definition of the `subprotocolBody`. + +| **Property** | **Value** | +| --- | --- | +| [https://w3id.org/edc/v0.0.1/ns/id](https://w3id.org/edc/v0.0.1/ns/id) | `{{CONNECTOR_ASSET_ID}}` specified in the DSP endpoint of the SubmodelDescriptor (see [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition)) | + +*Table 8: Connector data assets request properties values* + +An example connector data asset definition is given below. + +>**Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "dct": "http://purl.org/dc/terms/", + "aas-semantics": "https://admin-shell.io/aas/3/0/HasSemantics/" + }, + "@id": "{{CONNECTOR_ASSET_ID}}", + "properties": { + "dct:type": {"@id": "cx-taxo:Submodel"}, + "cx-common:version": "3.0", + "aas-semantics:semanticId": {"@id": "urn:samm:io.catenax.days_of_supply:2.0.0#DaysOfSupply"} + }, + "privateProperties": { + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "{{ SUBMODEL_ENDPOINT }}", + "proxyQueryParams": "false", + "proxyBody": "false", + "proxyPath": "true", + "proxyMethod": "false", + } +} +``` + +#### 4.1.2 INDUSTRY CORE PART TYPE TWIN REGISTRATION AND DEFINITION + +##### 4.1.2.1 SHELL DESCRIPTOR REGISTRATION + +To allow partners to receive the actual "*Days of Supply*" data as defined in [Chapter 3](#3-aspect-models), +the provider **MUST** register a Shell Descriptor in the dDTR (see [[CX-0002]](#61-normative-references)) so that a partner: + +- May lookup the Industry Core Part Type Twin based on known identification data. +- May identify the connector endpoint providing access to the "Days of Supply" submodel data. + +The Shell Descriptors represent an Industry Core Part Type Twin and **MUST** follow the rules as defined +in [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids). + +The Shell Descriptor **MUST** be configured with the set of properties as defined in the table below. + +| **Object in ShellDescriptor** | **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | --- | +| | ***id*** | Defines the technical ID of the Asset Administration Shell representing a partner's twin. | **MUST** be unique following Industry Core Part Type standard ([[CX-0126]](#61-normative-references)) and is a technical Id randomly assigned as multiple Part Type Twins may be created for one Part Type. E.g. this number differs for the twins created at supplier and customer side. | +| | ***globalAssetId*** | Defines the Catena-X ID of the twin. | **MUST** be aligned with the partner's material. When referring to the same Part Type Twin, the same number **MUST** be used (see [[CX-0126]](#61-normative-references)). | +| | **specificAssetIds** | Identifiers that may be used to lookup Part Type Twins. | **MUST** be set to according to the Industry Core Part Type standard ([[CX-0126]](#61-normative-references)). See *Table 10* for respective specific asset IDs. The `"customerPartId"` **MUST** be set by Customers and **SHOULD** be set by Suppliers. | +| submodelDescriptor | **id** | Technical identifier of a SubmodelDescriptor. | **MUST** be set to a unique identifier. | +| submodelDescriptor | **semanticId** | The semantic identifier of the "Days of Supply" SAMM. | **MUST** be set to `{ "type": "ExternalReference", "keys": [{ "type": "GlobalReference", "value": "urn:samm:io.catenax.days_of_supply:2.0.0#DaysOfSupply" }] }` to externally define how the Submodel must be interpreted. | +| submodelDescriptor > endpoint | **interface** | Defines the Submodel Interface [[CX-0002]](#61-normative-references) and the version. | **MUST** be set to `"SUBMODEL-3.0"` to rely on current specification. | +| submodelDescriptor > endpoint > protocolInformation | **href** | Defines the direct link to the public API of the connector's data plane with a path that **SHOULD** be appended by the proxy, if needed. | **MUST** be set to the public API of the dataplane providing the data with the path appended to directly access the submodel. | +| submodelDescriptor > endpoint > protocolInformation | **subprotocol** | Defines the usage of the connector based on DSP to access and use the submodel. | **MUST** be set to `"DSP"` to define the connector endpoint of the subprotocol. | +| submodelDescriptor > endpoint > protocolInformation | **subprotocolBody** | Defines the asset id in the connector and the connector address to access and use the submodel. | **MUST** be set to `"id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}"` to provide the necessary information for contracting the submodel endpoint. Refer to [Chapter 4.1.2](#412-industry-core-part-type-twin-registration-and-definition) for the definition of the asset of the subprotocolBody. | + +*Table 9: Properties relevant for the Shell Descriptor definition* + +When searching the submodel in the dDTR of a provider, a consumer **SHOULD** use the specific asset IDs +as defined in [[CX-0126]](#61-normative-references). Table 10 gives an overview of the specific asset IDs that the data provider +added to the ShellDescriptor so that the data consumer may find the Industry Core Part Type Twin. + +| **Specific Asset Id** | **Value** | +| --- | --- | +| digitalTwinType | "PartType". Set to identify twins compliant to the Industry Core Part Type (see [[CX-0126]](#61-normative-references)). | +| manufacturerId | Supplier / Manufacturer partner BPNL (see [[CX-0010]](#61-normative-references)) | +| manufacturerPartId | Supplier / Manufacturer partner identification number of the part. | +| customerPartId | Customer partner identification number of the part. | + +*Table 10: Specific asset IDs of Industry Core Part Type Twins proposed to be used to lookup a twin in the dDTR* + +The Shell Descriptor defines the metadata of the Industry Core Part Type Twin. The following example +Shell Descriptor represents a supplier's Shell Descriptor of a supplier who provides two customers access +to an "Days of Supply" submodel. For further information on the creation of Part Type Twins, +refer to [Chapter 2.1.4](#214-digital-twins-and-specific-asset-ids). + +Following [[CX-0002]](#61-normative-references), when searching the data assets catalog of a provider, a consumer **SHOULD** +use the `assetId` determined via `subprotocolBody` of the SubmodelDescriptor's endpoint definition +of subprotocol type `"DSP"` of the Submodel Descriptor of interest. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "id": "{{TECHNICAL_TWIN_ID}}", + "globalAssetId": "{{MATERIAL_NUMBER_CX}}", + "idShort": "Semiconductor", + "specificAssetIds": [ + { + "name": "digitalTwinType", + "value": "PartType", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "manufacturerPartId", + "value": "{{MATERIAL_NUMBER_SUPPLIER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "manufacturerId", + "value": "{{SUPPLIER_BPNL}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "customerPartId", + "value": "{{MATERIAL_NUMBER_CUSTOMER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{CUSTOMER_BPNL}}" + } + ] + } + }, + { + "name": "customerPartId", + "value": "{{MATERIAL_NUMBER_OTHER_CUSTOMER}}", + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "{{SUPPLIER_BPNL}}" + }, + { + "type":"GlobalReference", + "value":"{{OTHER_CUSTOMER_BPNL}}" + } + ] + } + } + ], + "submodelDescriptors": [ + { + "id": "e5c96ab5-896a-482c-8761-efd74777ca97", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.days_of_supply:2.0.0#DaysOfSupply" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "{{SUPPLIER_CONNECTOR_DATAPLANE_PUBLIC_API}}/{{PATH_IF_NEEDED}}", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ] + }, + { + "id": "a6c96ab5-896a-482c-8761-efd74777ca99", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "GlobalReference", + "value": "urn:samm:io.catenax.days_of_supply:2.0.0#DaysOfSupply" + } + ] + }, + "endpoints": [ + { + "interface": "SUBMODEL-3.0", + "protocolInformation": { + "href": "{{SUPPLIER_CONNECTOR_DATAPLANE_PUBLIC_API}}/{{PATH_IF_NEEDED}}", + "endpointProtocol": "HTTP", + "endpointProtocolVersion": [ + "1.1" + ], + "subprotocol": "DSP", + "subprotocolBody": "id={{CONNECTOR_ASSET_ID}};dspEndpoint={{SUPPLIER_CONNECTOR_DSP_ENDPOINT}}", + "subprotocolBodyEncoding": "plain", + "securityAttributes": [ + { + "type": "NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ] + } + ] +} +``` + +##### 4.1.2.2 LOOKING UP A PART TYPE TWIN IN THE DDTR + +To query the dDTR of a data provider, after contracting the usage via the data provider's connector +(see [[CX-0018]](#61-normative-references)), the lookup API (see [[CX-0002]](#61-normative-references)) can be used relying on the specific +asset IDs defined by the Industry Core Part Type (see [[CX-0126]](#61-normative-references)) that can be seen in +Table 10 (table of shellDescriptorRegistration with specific asset IDs). + +An example call relying on all information is given in the code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{PARTNER_CONNECTOR_DATA_PLANE}}/lookup/shells?assetIds={"name":"digitalTwinType", "value": "PartType"},{"name":"manufacturerPartId", "value": "{{MATERIAL_NUMBER_SUPPLIER}}"},{"name":"manufacturerId", "value": "{{SUPPLIER_BPNL}}"},{"name":"customerPartId", "value": "{{MATERIAL_NUMBER_CUSTOMER}}"} +``` + +As a result identifiers of the ShellDescriptors will be returned. With this data, a data provider can +read the ShellDescriptor to extract the endpoint data of the data provider. An example is given in the +code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{PARTNER_CONNECTOR_DATA_PLANE}}/shell-descriptors/{{AAS_IDENTIFIER}} +``` + +##### 4.1.2.3 FETCHING SUBMODEL DATA + +To fetch the *Days of Supply* Submodel data at the submodel endpoint of a data provider, after +contracting the usage via the data provider's connector (see [[CX-0018]](#61-normative-references)), the submodel API (see [[CX-0002]](#61-normative-references)) +can be used. + +An example call relying on all information is given in the code sample below. + +> **Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```code +GET: {{HREF_PATH}}/$value +``` + +## 5 PROCESSES + +> *This section is normative* + +### 5.1 DAYS OF SUPPLY PROCESS + +The determination of *Days of Supply,* the measure of how long stocks and projected stock will cover +demand, is predicated on the establishment and allocation of inventories to specific customers or +suppliers, following an existing order or call-off (Build-to-Order). This standard must not be +applied in situations where inventory is built up without a specific allocation to a customer or +supplier (Build-to-Stock). + +This information pertains to planning periods of about 1 to 4 weeks. This approach ensures a +comprehensive view that supports short-term operational planning without excluding considerations +for future supply projections. Thus, this standard facilitates a balanced perspective that includes +immediate availability as well as anticipated supply levels. + +Consequently, neither long-term planning nor strategic planning is included in its scope. + +We distinguish exactly two scenarios: + +1. On one hand, the exchange of information from supplier to customer and, +2. on the other hand, from customer to supplier. + +In both scenarios, information must not be shared horizontally under any circumstances. This means +that the *Days of Supply* in relation to other customers or suppliers must not be shared. + +The data exchange among C-X participants refers to the direct business relationship between them. In +the case of consignation, the warehouse is identified through the actual location - the +customer/supplier site. In this instance, the allocated stock is not considered as taken and, +according to our definition, not delivered (has not yet been shipped) + +### 5.2 DAYS OF SUPPLY PROVISIONING WITHIN SINGLE SOURCING AND SINGLE CUSTOMER SCENARIOS + +#### 5.2.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. The common definitions are found in +[Chapter 1.5](#15-terminology). This section describes respective scenarios. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Customer** | The customer acts as the data consumer and provider in this standard. | A business partner that procures items from its supplier and processes inquiries about its *Days of Supply* metrics related to the allocated stock/inventories. The customer shares information regarding its own *Days of Supply* in the context of the designated supplier. | +| **Supplier** | The supplier acts as the data consumer and provider in this standard. | A business partner that supplies items to a customer and requests information on the *Days of Supply* for allocated stock/inventories. The supplier shares details about the *Days of Supply* for items already produced for the customer, irrespective of the location of these stock/inventories. | + +*Table 11: Actors and roles 1* + +#### 5.2.2 PROCESS REPRESENTATION + +The exchange of information regarding *Days of Supply* occurs in both directions between the +customer and the supplier, meaning, information is shared from the customer to the supplier and vice +versa. The following example demonstrates how the object *Days of Supply* indicates the duration for +which the projected stock of a period would be sufficient to meet the demands of subsequent periods, +assuming no additional receipts occur during these periods. Thus, the exchange of *Days of Supply* +information early on reveals potential issues, allowing the customer to adjust its production +planning accordingly. + +**Note:** The *Days of Supply* information for both supplier and customer always refers to the value +at the end of the business day. The supplier's production output, determined at the end of the +business day, influences the *Days of Supply* for deliveries and the build up of stock for the +following day. + +**Recommended procedure in case of single sourcing with information about Days of Supply from customer to supplier and vice versa** + +**Customers' Days of Supply** + +This option provides a day-by-day forecast of the *Days of Supply*, incorporating the concept of +dynamically adjusting the planned stock against future demands in order to anticipate material +shortages. As the following table shows, in the customers' *Days of Supply* view, the stock +decreases through internal demand and increases through incoming deliveries. + +*Note: In this example the calculations are as follows:* + +| **Customers' Days of Supply** | **Key Figures** | **Day 0** | **Day 1** | **Day 2** | **Day 3** | **Day 4** | **Day 5** | **Day 6** | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Production ends at 23:59:57 | Demand | | 40 | 60 | 50 | 50 | 60 | 50 | +| Deliveries arrive at 23:59:58 | Delivery (incoming) | | 0 | 60 | 100 | 0 | 0 | 40 | +| Stock Stand at 23:59:59 | Projected Item Stock | 100 | 60 | 60 | 110 | 60 | 0 | -10 | +| | Days of Supply | 2.00 | 1.00 | 1.20 | 2.00 | 1.00 | 0.80 | | + +*Table 12: Single sourcing customer example* + +It is assumed that the customer has an initial inventory of 100 items in the warehouse, which are +relevant for the calculation of customers' *Days of Supply* for the following day(s). On day 1, a +demand of 40 items is fully met by the existing inventory, leaving 60 items. This remaining stock is +exactly enough to satisfy the demand on day 2 of 60 items (Demand day 1: 40 + Demand day 2: 60), +resulting in a *Days of Supply* of 2.00 days. + +**Days of Supply on Day 1** + +On Day 1, due to no further deliveries, the projected item stock is insufficient to meet the +outgoing demand expected on day 3. As a result, the Days of Supply, calculated based on the inventory +at the end of day 1, is 1.00 day. + +**Days of Supply on Day 2** + +On day 1, 60 remained in stock. These are enough to meet the demand of 60 on day 2. With the +addition of new planned receipts/stocks of 60 items on day 2, the Projected Item Stock at the end of +the day remains at 60. This is sufficient to completely cover the demand for the third day (50). The +remaining 10 are sufficient to cover 20 percent (10/50 = 0.2) of the demand of 50 on Day 4. The +*Days of Supply* on day 2 is 1.20 days. + +**Days of Supply on Day 3** + +At the end of Day 3, the Projected Item Stock is 110. This is sufficient for day 4 (Demand day 4: 50 + Demand day 5: 60). The *Days of Supply* is therefore 2.00 on the third day. + +**Days of Supply on Day 4** + +At the end of day 4, the Projected Item Stock is 60. No further deliveries are expected/No +deliveries of goods have arrived. Thus, the *Days of Supply* on day 4 is 1.00. + +**Days of Supply on Day 5** + +At the end of day 5, the Projected Item Stock is 0. The demand on day 5 (60) was met by the previous +day's Projected Item Stock (60). Thus, the *Days of Supply* on day 5 is 0.80 + +**Days of Supply on Day 6** + +At the end of day 6, the Projected Item Stock is 0, and therefore cannot cover any demands in the +subsequent periods. + +**Suppliers' Days of Supply** + +This option provides a day-by-day forecast of the *Days of Supply*, incorporating the concept of +dynamically adjusting the planned stock against future demands in order to anticipate material +shortages. As the following table shows, in the suppliers' Days of Supply view, the stock decreases +through outgoing deliveries and increases through internal production. + +*Note: In this example the calculations are as follows:* + +| **Suppliers' Days of Supply** | **Key Figures** | **Day 0** | **Day 1** | **Day 2** | **Day 3** | **Day 4** | **Day 5** | **Day 6** | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Shipment ends at 23:59:57 | Delivery (outgoing) | | 40 | 60 | 50 | 50 | 60 | 50 | +| Internal Production at 23:59:58 | Production Output | | 0 | 60 | 100 | 0 | 0 | 40 | +| Stock Stand at 23:59:59 | Projected Item Stock | 100 | 60 | 60 | 110 | 60 | 0 | -10 | +| | Days of Supply | 2.00 | 1.00 | 1.20 | 2.00 | 1.00 | 0.80 | | + +*Table 13: Single sourcing supplier example* + +It is assumed that the supplier has an initial inventory of 100 items in the warehouse, which are +relevant for the calculation of suppliers' *Days of Supply* for the following day(s). On day 1, a +delivery (outgoing) of 40 items is fully met by the existing inventory, leaving 60 items. This +remaining stock is exactly enough to satisfy the delivery (outgoing) on day 2 of 60 items (Delivery +(outgoing) day 1: 40 + Delivery (outgoing) day 2: 60), resulting in a *Days of Supply* of 2.00 days. + +**Day 1** + +On Day 1, due to no production output, the projected item stock is insufficient to meet the delivery +(outgoing) expected on day 3. As a result, the *Days of Supply*, calculated based on the inventory +at the end of day 1, is 1.00 day. + +**Day 2** + +On day 1, 60 remained in stock. These are enough to meet the delivery (outgoing) of 60 on day 2. +With the addition of new planned receipts/stocks of 60 items on day 2, the Projected Item Stock at +the end of the day remains at 60. This is sufficient to completely cover the delivery (outgoing) for +the third day (50). The remaining 10 are sufficient to cover 20 percent (10/50 = 0.2) of the +delivery (outgoing) of 50 on Day 4. The *Days of Supply* on day 2 is 1.20 days. + +**Day 3** + +At the end of Day 3, the Projected Item Stock is 110. This is sufficient for day 4 (Delivery +(outgoing) day 4: 50 + Delivery (outgoing) day 5: 60). The *Days of Supply* is therefore 2.00 on the +third day. + +**Day 4** + +At the end of day 4, the Projected Item Stock is 60. No further production output is expected/There +is no production output. Thus, the *Days of Supply* on day 4 is 1.00. + +**Day 5** + +At the end of day 5, the Projected Item Stock is 0. The delivery on day 5 (60) was met by the +previous day's Projected Item Stock (60). Thus, the *Days of Supply* on day 5 is 0.80 + +**Day 6** + +At the end of day 6, the Projected Item Stock is 0, and therefore cannot cover any delivery +(outgoing) in the subsequent periods. + +**Important Note:** + +- For more information on how to calculate the allocated Item Stock please see below in the Annex. + +### 5.3 DAYS OF SUPPLY MANAGEMENT WITHIN MULTI-SOURCING SCENARIOS + +#### 5.3.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. The common definitions are found in[Chapter 1.5](#15-terminology). This section describes respective scenarios. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Customer** | The customer acts as the data provider in this standard. | A business partner that procures items from its supplier and provides information about its own *Days of Supply* in relation to the assigned supplier. | +| **Supplier A** | The supplier A acts as the data consumer in this standard. | A business partner that supplies items to a customer and requests information on the *Days of Supply* for allocated stock/items from the customer. Regardless of the warehouse in which the inventory is held. Supplier A has no knowledge of the business relationship between the customer and Supplier B. | +| **Supplier B** | The supplier B acts as the data consumer in this standard. | A business partner that supplies items to a customer and requests information on the Days of Supply for allocated stock/items from the customer. Regardless of the site in which the inventory is located. Supplier B has no knowledge of the business relationship between the customer and Supplier A. | + +*Table 14: Actors and roles 2* + +#### 5.3.2 PROCESS REPRESENTATION + +**Note:** Multi-sourcing: In this case one customer has more than one supplier for one item. +Customer **MUST** make sure that allocated *Days of Supply* based on Allocated Item Stock are sent +to the particular supplier and **MUST** avoid horizontal exchange of competitive sensible +information. On how to calculate Allocated Item Stock please see the **Annex 1**. Once the allocated +item stock is calculated, the *Days of Supply* allocation is calculated using the process described in +[Chapter 5.2.2](#522-process-representation). + +### 5.4 DAYS OF SUPPLY MANAGEMENT WITHIN MULTI-CUSTOMER SCENARIO + +#### 5.4.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. The common definitions are found +in [Chapter 1.5](#15-terminology). This section describes respective scenarios. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Customer A** | The customer acts as the data consumer in this standard. | A business partner that procures items from its supplier and requests information about the supplier's allocated item stock information. | +| **Customer B** | The customer acts as the data consumer in this standard. | A business partner that procures items from its supplier and requests information about the supplier's allocated item stock information. | +| **Supplier** | The supplier acts as the data provider in this standard. | A business partner that supplies items to more than one customer. It provides the item stock already produced for the customer. Regardless of the site in which the item stock is located. | + +*Table 15: Actors and roles 3* + +#### 5.4.2 PROCESS REPRESENTATION + +**Note:** Multi-customer: In this case one supplier delivers the same item to more than one +customer. Supplier **MUST** make sure that allocated DoS based on allocated Item Stock are sent to +the particular customer and **MUST** avoid horizontal exchange of competitive sensible information. +On how to calculate Allocated Item Stock please see the **Annex 2**. Once the allocated item stock is +calculated, the *Days of Supply* allocation is calculated using the process described in [Chapter 5.2.2](#522-process-representation). + +### 5.5 DAYS OF SUPPLY USE OF ASSIGNMENT TO SITES AND ADDRESSES + +#### 5.5.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. The common definitions are found in +[Chapter 1.5](#15-terminology). This section describes respective scenarios. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Customer** | The customer acts as the data consumer and provider in this standard. | Is a business partner that procures items from its supplier and requests information about its allocated Days of Supply. The customer provides information about its own Days of Supply in relation to the assigned supplier. | +| **Supplier** | The supplier acts as the data consumer and provider in this standard. | Is a business partner that supplies items to a customer. It requests information on the Days of Supply for allocated stock/items from the customer and provides information on the Days of Supply for items already produced for the customer. Regardless of the site in which the inventory is located. | + +*Table 16: Actors and roles 4* + +#### 5.5.2 PROCESS REPRESENTATION + +The distinction between customer and supplier locations must be made via the unique breakdown to +BPNS and BPNA. This means that a legal entity can have several sites and addresses with its BPNL and +these are mapped via the BPNS and BPNA. This distinction is used because a location is always +assigned to the customer and supplier via the site with its BPNS. However, a site can have several +addresses, e.g. for delivery. Furthermore, additional addresses can belong to a site via +consignation and external warehouses. It is therefore also possible that, for example, the customer +address is the same as the address of the external warehouse which is assigned to the supplier. In +addition, the delivery information may also be enriched in this way, because a delivery time results +from the respective location with its address. + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [CX-0001] | EDC Discovery API | 1.0.2 | +| [CX-0002] | Digital Twins in Catena-X | 2.2.0 | +| [CX-0003] | SAMM Aspect Meta Model | 1.1.0 | +| [CX-0006] | Registration and initial onboarding | 2.0.0 | +| [CX-0010] | Business Partner Number (BPN) | 2.0.0 | +| [CX-0018] | Dataspace Connectivity | 3.0.0 | +| [CX-0053] | Discovery Finder and BPN Discovery Service APIs | 1.1.0 | +| [CX-0118] | Delivery Information Exchange | 2.0.0 | +| [CX-0120] | Short-term Material Demand Exchange | 2.0.0 | +| [CX-0121] | Planned Production Output Exchange | 2.0.0 | +| [CX-0122] | Item Stock Exchange | 2.0.0 | +| [CX-0126] | Industry Core Part Type | 2.0.0 | +| [CX-0128] | Demand and Capacity Management | 2.0.0 | +| [CX-0146] | Supply Chain Disruption Notifications | 1.0.0 | + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +| **Context** | **Link** | +| --- | --- | +| [CX-OMW] | Catena-X Operating Model Whitepaper. Download from: [Operating Model v2.pdf](https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf) | +| [CX-ODRL] | Catena-X ODRL Profile repository: https://github.com/catenax-eV/cx-odrl-profile | +| [RFC2119] | Bradner, S. Key words for use in RFCs to Indicate Requirement Levels. Available online: https://datatracker.ietf.org/doc/html/rfc2119 +| [RFC8174] | Leiba, B. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. Available online: https://datatracker.ietf.org/doc/html/rfc8174 | +| [SMT] | How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf | +| [IDTA-01002-3-0] | Specification of the Asset Administration Shell Part 2: Application Programming Interfaces. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API.pdf | + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +### ANNEXES + +## Multi-Sourcing and Multi-Customer scenarios for Allocated Item Stock + +Here are some examples on how to calculate allocated item stock in the multi-sourcing and multi-customer scenarios: + +### 1 ITEM STOCK PROVISIONING WITHIN MULTI-SOURCING SCENARIOS + +#### 1.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. The common definitions are found in +[Chapter 1.5](#15-terminology). This section describes respective scenarios. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Customer** | The customer acts as the data provider in this standard. | A business partner that procures items from its supplier and provides information about its own stock in relation to the assigned supplier. | +| **Supplier A** | The supplier A acts as the data consumer in this standard. | A business partner that supplies items to a customer and requests the allocated *Item Stock* from the customer. Regardless of the warehouse in which the *Item Stock* is located. Supplier A has no knowledge of the business relationship between the customer and Supplier B. | +| **Supplier B** | The supplier B acts as the data consumer in this standard. | A business partner that supplies items to a customer and requests the allocated *Item Stock* from the customer. Regardless of the site in which the *Item Stock* is located. Supplier B has no knowledge of the business relationship between the customer and Supplier A. | + +*Table A1.1: Actors and roles 2* + +#### 1.2 PROCESS REPRESENTATION + +Multi-sourcing is a common scenario in the field. Suppliers usually supply several customers with the +same material. And customers purchase the same material from different suppliers. Because of that, +in the case of multi-sourcing, when there is no possibility of differentiating the items received +from different suppliers (i.e. by using different item numbers for each supplier), the customer must +be aware that competition sensitive information from one supplier must not be shared with other +suppliers. After evaluating different alternatives, the following procedure is the one recommended +from the item stock standardization team and legal advisors to all users in order to ensure a +compliant exchange of information from customer to suppliers in the case of multi-sourcing. + +In this example, the shortage situation occurs at supplier B on days 5 and 6 and at supplier A on +days 8 and 9. To alleviate the shortage, a larger quantity is requested from supplier A on day 5 and +from supplier B on day 9. This ensures that the bottleneck situation has no effect on the customer's +production. + +**Recommended procedure in case of multi-sourcing with information exchange from customer to supplier: quoting consumption, keeping track of deliveries** + +*Note 1: in this example Item Stock A and Item Stock B make reference to the Item stock at the customer's site that is allocated respectively to supplier A and B.* + +*Note 2: in this example the calculations are as follows (example on Supplier A, also applies to Supplier B):* + +*Item Stock A (day n) = Item Stock A (day n-1) + Delivery A (day n) - Allocated consumption A (day n);* + +*if Stock B (day n) ≤ 0 then Allocated consumption A (day n new) = Allocated consumption A (day n old)+ |Stock B (day n)|* + +*and Stock B (day n new)= 0* + +*Note 3: This quote is only necessary in case keeping track of the parts supplied by different suppliers is not possible (i.e. by using different item numbers for each supplier):* + +![Table A1.2: Multi-source customer example](./assets/table_A1.2.svg) +*Table A1.2: Multi-source customer example* + +Note: In this standard, only current/actually *Item Stock* quantities are transmitted. + +This procedure (*quoting consumption, keeping track of deliveries*) takes in consideration the following aspects: + +- The customer may share with the supplier A the following information on a daily basis: +- + - Information on the volumes called off by the customer but only in relation to the specific supplier ("Allocated call-off A") + - the supply volumes delivered in response to this call off ("Delivery A") (covered by the standard [[CX-0118]](#61-normative-references)) + - the consumption allocated to the supplier's products ("Allocated consumption A") (covered by the standard [[CX-0120]](#61-normative-references)) + - the actual *Item Stock* at the customer ("Item Stock A"), (covered in this standard) + +- The customer must not share the following information with the supplier and the supplier must not otherwise be able to derive this information from the information available to it: + +- + - Capacity data of other suppliers, + - the overall volumes called off by the customers ("Call off customer TOTAL"), + - information on the volumes called off by the customer in relation to another supplier ("Allocated call off B"), + - the supply volumes delivered by another supplier ("Delivery B"), + - the overall consumption delivered by all suppliers ("Consumption customer TOTAL"), + - the consumption allocated to another supplier ("Allocated consumption B"), + - the customer's total *Item Stock*("Item stock customer TOTAL"), (covered in this standard) + - the *Item Stock* from another supplier at the customer ("Item Stock B"). (covered in this standard) + +Note: For Supplier B, the same procedure applies in reverse. + +### 2 ITEM STOCK PROVISIONING WITHIN MULTI-CUSTOMER SCENARIO + +#### 2.1 ACTORS AND ROLES + +The following actors and roles occur in the described processes. The common definitions are found in +Chapter 1.5. This section describes respective scenarios. + +| **Actors** | **Role** | **Description** | +| --- | --- | --- | +| **Customer A** | The customer acts as the data consumer in this standard. | A business partner that procures items from its supplier and requests information about the supplier's allocated *Item Stock* information. | +| **Customer B** | The customer acts as the data consumer in this standard. | A business partner that procures items from its supplier and requests information about the supplier's allocated *Item Stock* information. | +| **Supplier** | The supplier acts as the data provider in this standard. | A business partner that supplies items to more than one customer. It provides the *Item Stock* already produced for the customer. Regardless of the site in which the *Item Stock* is located. | + +*Table A2.1: Actors and roles 3* + +**2.2 PROCESS REPRESENTATION** + +In this scenario, two customers procure the same item from one supplier. In addition to the *Item Stock*, the call-offs and the actual delivery quantity are displayed once for each day. There is a +distribution of the supplier's total production output in a ratio of 1:3, i.e. each customer +receives 1/3 of the planned production quantity and 1/3 is left in the supplier's warehouse. The +information transmitted must be separated for each customer. The information must not be shared +horizontally under any circumstances. This means that the *Item Stock* in relation to other +customers must not be shared. On day 5 and 6, a complete production downtime occurs at the supplier. +The supplier now supplies its customers from its own stock and transmits the *Item Stock* +information in the corresponding ratio. From day 7, production continues as planned. + +**Recommended procedure in case of multi customer with single sourcing** + +![Table A2.2: Single supplier to multi customer example](./assets/table_A2.2.svg) +*Table A2.2: Single supplier to multi customer example* + +A suitable measure must be found for the allocation and provision of information. We recommend the +use of the ratio or the quoting of the call-off. + +Note: In this standard, only current/actual *Item Stock* quantities are transmitted. + +This procedure takes in consideration the following aspects: + +- The customer may share with the supplier the following information on a daily basis: + - Information on the volumes called off by the customer + - the supply volumes delivered in response to this call-off (covered by the standard [[CX-0118]](#61-normative-references)) + - the consumption allocated to the supplier's products (covered by the standard [[CX-0120]](#61-normative-references)) + - the actual *Item Stock* of its products at the customer's site (covered in this standard) + +- The supplier may share with the customers the following information on a daily basis: + - the supply volumes delivered in response to the customer's call off (covered by the standard [[CX-0118]](#61-normative-references)) + - the production output allocated to the customer's material or products (covered by the standard [[CX-0121]](#61-normative-references)) + - the actual *Item Stock* of its material or products at the supplier site (covered in this standard) + +- The supplier must not share the following information with the customer and the customer must + not otherwise be able to derive this information from the information available to it: + - Capacity and delivery data of other customer, + - the overall volumes called off by the customers, + - the supply volumes delivered to another customer, + - the supplier's total *Item Stock* (covered in this standard), + - the supplier *Item Stock* allocated for another customer (covered in this standard) + +### REFERENCES + +| **Number / Reference** | **Standard / Context** | +| --- | --- | +| Chapter 5.2.2 / Calculation Days of Supply | Information on SAP's Calculation of Days of Supply https://help.sap.com/saphelp_snc70/helpdata/en/c8/96cb530898214be10000000a174cb4/content.htm | + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_1.svg b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_1.svg new file mode 100644 index 000000000..82da45389 --- /dev/null +++ b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_1.svg @@ -0,0 +1,4 @@ + + + +
    Data Provider
    Data Provider
    Connector
    Connector
    Busines Application
    Busines App...
    Catena-X Core Service Provider
    Catena-X Core Service Provider
    IAM
    IAM
    Credential Service
    Credential S...
    Keycloak
    Keycloak
    Data Consumer
    Data Consumer
    Connector
    Connector
    Busines Application
    Busines Applicati...
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
      Authentication / Authorization  
    (8) Get Submodel
    (8) Get Su...
    (5) Query dDTR for Twin and submodel
    (5) Query dDTR for Twin and submodel
    (4) Connector Communication
      (Catalog / Contracting / Transfer)  
    (4) Connector Communication...
    dDTR
    dDTR
    Submodel Endpoint
    Submodel E...
    (10) Get Submodel
    (10) Get S...
    (3) Register Twin
    with Submodels
    (3) Register Twin...
    (2) Register Submodel Endpoint
     at Connector
    (2) Register Submodel Endpoint...
    (9)
    (9)
    Text
    Text
    (6) Get lookup/shells
    by specific asset ids
    (6) Get lookup/shells...
    (1) Register dDTR at Connector
    (1) Register dDTR at Connector
    (7) Get shell-descriptors
    by AAS ID
    (7) Get shell-descriptors...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_2.svg b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_2.svg new file mode 100644 index 000000000..745f8280d --- /dev/null +++ b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_2.svg @@ -0,0 +1,4 @@ + + + +
    represents same material
    equivalent specific asset IDs, global asset ID,
    different AAS ID
    represents same material...
    PartType for Material (e.g. "Semiconductor")
    PartType for Material...
    Supplier
    Supplier
    Customer
    Custom...
    Asset
    registered in dDTR as AAS
    Asset...
    Submodel
    Submodel
    PartType for Material "Control Unit"
    PartType for Materia...
    DaysOfSupply

    (Direction = Outgoing)
    DaysOfSupply...
    DaysOfSupply

    (Direction = Incoming)
    DaysOfSupply...
    PartTypeInformation
    PartTypeInformation
    SingleLevelUsageAs Planned
    SingleLevelUsageAs P...
    submodel of
    submodel of
    submodel of
    submodel of
    references twin
    references twin
    PartTypeInformation
    PartTypeInformation
    SingleLevel
    BomAsPlanned
    SingleLevel...
    references twin
    references twin
    submodel of
    submodel of
    submodel of
    submodel of
     Legend
     Legend
    Digital Twin in DTR
    Digital Twin in DTR
    Submodel (CX - 0145)
    Submodel (CX - 0145)
    Submodel (IC Part Type)
    Submodel (IC Part Type)
    submodel of
    submodel of
    references twin
    references twin
    PartType for Material "Semiconductor"
    PartType for Materia...
    submodel of
    submodel of
    submodel of
    submodel of    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_3.puml b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_3.puml new file mode 100644 index 000000000..f46a51236 --- /dev/null +++ b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_3.puml @@ -0,0 +1,43 @@ +@startuml Figure_3 +title Shared Digital Approach - Registration of IC Part Type Twin + +autonumber + +box "Supplier" #LightBlue + participant SupplierApplication as "Application" + participant SupplierDTR as "dDTR" + participant SupplierSubmodelEndpoint as "Submodel Endpoint" + participant SupplierEDC as "Connector" +end box + +box "Customer" #LightGreen + participant CustomerEDC as "Connector" + participant CustomerSubmodelEndpoint as "Submodel Endpoint" + participant CustomerDTR as "dDTR" + participant CustomerApplication as "Application" +end box + +== Supplier registers IC Part Type Twin with Submodel for Customer == + + note over SupplierApplication, SupplierSubmodelEndpoint: Supplier created Part Type Twin + + +== Customer registers IC Part Type Twin with Submodel for Supplier == + CustomerApplication -> CustomerEDC: Register dDTR for partner at Connector + activate CustomerEDC + return OK + + note over CustomerSubmodelEndpoint, CustomerApplication: Keeping Submodel updated only needed\nfor repository pattern + CustomerApplication -> CustomerSubmodelEndpoint: Create Submodel + activate CustomerSubmodelEndpoint + return OK + + CustomerApplication -> CustomerEDC: Register endpoint of Submodel for READ access for partner at Connector + activate CustomerEDC + return OK + + CustomerApplication -> CustomerDTR: Register IC Part Type Twin Shell Descriptor\n with Submodel endpoint\nfor Partner in dDTR\n(DSP endpoint) + activate CustomerDTR + return OK + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_3.svg b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_3.svg new file mode 100644 index 000000000..7372884ad --- /dev/null +++ b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_3.svg @@ -0,0 +1,53 @@ +Shared Digital Approach - Registration of IC Part Type TwinSupplierCustomerApplicationApplicationdDTRdDTRSubmodel EndpointSubmodel EndpointConnectorConnectorConnectorConnectorSubmodel EndpointSubmodel EndpointdDTRdDTRApplicationApplicationSupplier registers IC Part Type Twin with Submodel for CustomerSupplier created Part Type TwinCustomer registers IC Part Type Twin with Submodel for Supplier1Register dDTR for partner at Connector2OKKeeping Submodel updated only neededfor repository pattern3Create Submodel4OK5Register endpoint of Submodel for READ access for partner at Connector6OK7Register IC Part Type Twin Shell Descriptorwith Submodel endpointfor Partner in dDTR(DSP endpoint)8OK \ No newline at end of file diff --git a/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_4.puml b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_4.puml new file mode 100644 index 000000000..e7732af18 --- /dev/null +++ b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_4.puml @@ -0,0 +1,84 @@ +@startuml Figure_4 +title Shared Digital Twin Approach - Lookup of IC Part Type Twin + +autonumber + +box "Supplier" #LightBlue + participant SupplierApplication as "Application" + participant SupplierDTR as "dDTR" + participant SupplierSubmodelEndpoint as "Submodel Endpoint" + participant SupplierEDC as "Connector" +end box + +box "Customer" #LightGreen + participant CustomerEDC as "Connector" + participant CustomerSubmodelEndpoint as "Submodel Endpoint" + participant CustomerDTR as "dDTR" + participant CustomerApplication as "Application" +end box + + +== Customer updates Submodel information (repository pattern only) == + note over CustomerSubmodelEndpoint, CustomerApplication: Keeping Submodel updated only needed\nfor repository pattern + CustomerApplication -> CustomerSubmodelEndpoint: Update Submodel information + activate CustomerSubmodelEndpoint + return OK + + +== Supplier reads (updated) Submodel from Customer == + + SupplierApplication -> SupplierEDC: Query Connector Catalog for Customer dDTR access + activate SupplierEDC + + SupplierEDC <-> CustomerEDC: DSP communication + + return Catalog + + SupplierApplication -> SupplierEDC: Negotiate Contract and init transfer + activate SupplierEDC + SupplierEDC <-> CustomerEDC: DSP communication + return OK + + SupplierApplication -> CustomerEDC: Query DTR for IC Part Type Twin based on specific asset ids + activate CustomerEDC + CustomerEDC -> CustomerDTR: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerDTR + CustomerDTR --> CustomerEDC + deactivate CustomerDTR + return ShellDescriptor Ids + + SupplierApplication -> SupplierApplication: select ShellDescriptor ID\nto get ShellDescriptor for\nIC Part Type Twin + + SupplierApplication -> CustomerEDC: Lookup IC Part Type Twin based on ShellDescriptor Id + activate CustomerEDC + CustomerEDC -> CustomerDTR: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerDTR + CustomerDTR --> CustomerEDC + deactivate CustomerDTR + return ShellDescriptor + + SupplierApplication -> SupplierApplication: Extract DSP Endpoint and Connector Asset ID for Submodel + + SupplierApplication -> SupplierEDC: Query Connector Catalog for Submodel based on Connector Asset ID + activate SupplierEDC + + SupplierEDC <-> CustomerEDC: DSP communication + + return Catalog + + SupplierApplication -> SupplierEDC: Negotiate Contract for Submodel and init transfer + activate SupplierEDC + SupplierEDC <-> CustomerEDC: DSP communication + return OK + + SupplierApplication -> CustomerEDC: Read Submodel + activate CustomerEDC + CustomerEDC -> CustomerSubmodelEndpoint: forward request based on Connector asset definitions\n(consumer proxy) + activate CustomerSubmodelEndpoint + CustomerSubmodelEndpoint --> CustomerEDC + deactivate CustomerSubmodelEndpoint + return Submodel + + SupplierApplication -> SupplierApplication: Use Submodel + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_4.svg b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_4.svg new file mode 100644 index 000000000..d008add16 --- /dev/null +++ b/docs/standards/CX-0145-DaysofsupplyExchange/assets/figure_4.svg @@ -0,0 +1,94 @@ +Shared Digital Twin Approach - Lookup of IC Part Type TwinSupplierCustomerApplicationApplicationdDTRdDTRSubmodel EndpointSubmodel EndpointConnectorConnectorConnectorConnectorSubmodel EndpointSubmodel EndpointdDTRdDTRApplicationApplicationCustomer updates Submodel information (repository pattern only)Keeping Submodel updated only neededfor repository pattern1Update Submodel information2OKSupplier reads (updated) Submodel from Customer3Query Connector Catalog for Customer dDTR access4DSP communication5Catalog6Negotiate Contract and init transfer7DSP communication8OK9Query DTR for IC Part Type Twin based on specific asset ids10forward request based on Connector asset definitions(consumer proxy)11 12ShellDescriptor Ids13select ShellDescriptor IDto get ShellDescriptor forIC Part Type Twin14Lookup IC Part Type Twin based on ShellDescriptor Id15forward request based on Connector asset definitions(consumer proxy)16 17ShellDescriptor18Extract DSP Endpoint and Connector Asset ID for Submodel19Query Connector Catalog for Submodel based on Connector Asset ID20DSP communication21Catalog22Negotiate Contract for Submodel and init transfer23DSP communication24OK25Read Submodel26forward request based on Connector asset definitions(consumer proxy)27 28Submodel29Use Submodel \ No newline at end of file diff --git a/docs/standards/CX-0145-DaysofsupplyExchange/assets/table_A1.2.svg b/docs/standards/CX-0145-DaysofsupplyExchange/assets/table_A1.2.svg new file mode 100644 index 000000000..3bbb87f71 --- /dev/null +++ b/docs/standards/CX-0145-DaysofsupplyExchange/assets/table_A1.2.svg @@ -0,0 +1 @@ +Normal Consumption1000100%Quote Supplier A60060%Quote Supplier B40040%SituationShortage Supplier BShortage Supplier BShortage Supplier AShortage Supplier ADay 1Day 2Day 3Day 4Day 5 -PlanDay 5 –IsDay 6 -PlanDay 6 -IsDay 7 PlanDay 7 IsDay 8 PlanDay 8 IsDay 9 PlanDay 9 IsDay 10Day 11Call off customer TOTAL1200100012001000120012001000100012001200100010001200120010001200Allocated call off A7206007206007201100600600720720600600720720600720Allocated call off B480400480400480480400400480480400400480480400480Delivery A7206007206007201100*600600720720600200**720220600720Delivery B480400480400480100**4000**480480400400480780*400480Consumption customer TOTAL1000100010001000100010001000100010001000100010001000100010001000Allocated consumption A6006006006006007406001000600600600520600220600600Allocated consumption B4004004004004002604000400400400480400780400400Item stock customer TOTAL200200400400600600600200600600600040000200Item Stock A120120240240360600600200320320320012000120Item Stock B80801601602400008080800800080*Manual intervention to increase delivery quantity**Shortage situation Delivery quantity remained below planTransferable information from item stock per day \ No newline at end of file diff --git a/docs/standards/CX-0145-DaysofsupplyExchange/assets/table_A2.2.svg b/docs/standards/CX-0145-DaysofsupplyExchange/assets/table_A2.2.svg new file mode 100644 index 000000000..dbb713cdc --- /dev/null +++ b/docs/standards/CX-0145-DaysofsupplyExchange/assets/table_A2.2.svg @@ -0,0 +1 @@ +ConsumptionCustomer A100033%Consumtpion Customer B100033%Production Output Supplier3000100%SituationProdSup100%Prod Sup 100%Prod Sup 100%Shortage Sup prod 0%Shortage Sup prod 0%Prod Sup 100%Day 1Day 2Day 3Day 4Day 5 -PlanDay 5 -IsDay 6 -PlanDay 6 -IsDay 7 PlanDay 7 IsCall off Customer A1000100010001000100010001000100010001000Call of Customer B1000100010001000100010001000100010001000Delivery to Customer A1000100010001000100010001000100010001000Delivery to Customer B1000100010001000100010001000100010001000Item Stock Supplier site TOTAL1000200030004000500020003000010001000Item Stock Supplier site for Customer A5001000150020002500100015000500500Item Stock Supplier site for Customer B5001000150020002500100015000500500Transferable information from item stock per day \ No newline at end of file diff --git a/docs/standards/CX-0146-SupplyChainDisruptionNotifications/CX-0146-SupplyChainDisruptionNotifications.md b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/CX-0146-SupplyChainDisruptionNotifications.md new file mode 100644 index 000000000..9914863e5 --- /dev/null +++ b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/CX-0146-SupplyChainDisruptionNotifications.md @@ -0,0 +1,909 @@ +# CX-0146 Supply Chain Disruption Notifications 1.0.0 + +## ABSTRACT + +The Catena-X *Supply Chain Disruption Notifications* Standard is created for all members of the +automotive supply chain. The aim is to have a functionality to easily and quickly inform the +affected supply chain partners in case of supply chain disruptions at some point in the value chain. +Having this information is key to be able to take the right countermeasures and make the whole value +chain more resilient. Recent incidents (e.g. semi-conductor-crisis or COVID pandemic) have +demonstrated the requirement for such a fast standardized process among all partners. + +## FOR WHOM IS THE STANDARD DESIGNED + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +This is the first version of the standard. + +## 1 INTRODUCTION + +This standard focuses on any kind of supply chain disruptions and aims to tackle the following +challenges: + +- information exchange between supply chain partners regarding their short-/mid- and long-term + demand and capacity status is slow and error prone +- lack of standards complicates the exchange of information +- lack of trust between the partners involved prevents the exchange of data +- current IT solutions provide bilateral (i.e. one-to-one) data exchange and often do not scale well + (i.e. one-to-n) + +This often leads to shortages, high expenses for "fire fighting" in the supply chain, production +disruptions, and ultimately to dissatisfied customers. + +The *Supply Chain Disruption Notifications* exchange contributes to the early detection and +management of supply chain disruptions (e.g. bottlenecks, capacity surpluses, etc.). + +This is enabled by the following standardized components: + +- common understanding of the *Supply Chain Disruption Notifications* objects as a basis for its + exchange between partners in a sovereign manner through a data model and the associated semantics +- application interoperability through the description of an API for the actual notification + exchange +- processes for the actual notification provisioning in order to support the contextual and legal + correctness + +In summary, the standardization provides a unified and streamlined method for notification exchange +between supplier and customer, thus improving efficiency, reducing errors, and ensuring quick +responses to any potential supply chain related challenges. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +This standard is intended for: + +- Data Provider +- Data Consumer +- Business Application Provider + +who are involved in a customer and supplier relationship within the automotive industry. + +For clarity on the roles and responsibilities of each actor, please see [Chapter 5.2](#52-actors--roles). The scope of +this standard is the exchange of *Supply Chain Disruption Notifications*. It does not cover any +specific countermeasures between partners in the one-to-one business relationship as a result of the +notification process. + +Illustrations and descriptions of roles are provided to help explain concepts and processes but are +not mandatory (see [Chapter 5.2](#52-actors--roles)). + +This standard requires that data consumers, providers and business application providers must adopt +the uniform business logic (according to [Chapter 5](#5-processes)), data models and data exchange protocols to +ensure interoperable data exchange. + +This standard focuses on direct one-to-one business relationships between customers and suppliers. + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +This standard defines the data models and APIs required for the exchange of *Supply Chain Disruption Notifications*. Implementing it ensures that: + +- all actors exchange *Supply Chain Disruption Notifications* in an identical manner. +- all actors process *Supply Chain Disruption Notifications* data in an identical manner. +- all actors exchange *Supply Chain Disruption Notifications* data only via a connector conformant to [[CX-0018]](#61-normative-references). +- all actors interpret the exchanged *Supply Chain Disruption Notifications* data in an identical manner. + +The APIs must only be used in the context of Catena-X and must only be accessible via a connector +conformant to [[CX-0018]](#61-normative-references). + +### 1.3 CONFORMANCE AND PROOF OF CONFORMITY + +> *This section is non-normative* + +Non-mandatory sections include authoring guidelines, diagrams, examples and notes. All other content +is mandatory. + +The capitalized key words such as **MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD** +and **SHOULD NOT** are to be interpreted as defined in [BCP 14] [[RFC2119]](#62-non-normative-references) [[RFC8174]](#62-non-normative-references). + +Participants must demonstrate conformity with Catena-X standards. Conformity Assessment Bodies (CABs) +verify that standards are correctly applied. + +**Proof of Conformity for Data Models** + +Participants must implement and conform to the standardized Data Models as outlined in [Chapter 3](#3-aspect-models). + +**Proof of Conformity for APIs** + +Participants must implement and conform to the standardized APIs as detailed in [Chapter 4](#4-application-programming-interfaces). + +**Proof of Conformity for Process & Core Business Logic** + +Participants must implement and conform to the *Supply Chain Disruption Notifications* core business +logic as described in [Chapter 5](#5-processes). + +### 1.4 EXAMPLES + +The following JSONs provide an example of the value-only serialization of the *Supply Chain Disruption Notification* +aspect model for a sample notification. The notification informs about a strike resulting in a demand +reduction between 12.12.2023 and 17.12.2023. + +```json +{ + "affectedSitesSender": [ + "BPNS7588787849VQ" + ], + "affectedSitesRecipient": [ + "BPNS6666787765VQ" + ], + "materialNumberSupplier": [ + "MNR-8101-ID146955.001" + ], + "contentChangedAt": "2023-12-13T15:00:00+01:00", + "startDateOfEffect": "2023-12-13T15:00:00+01:00", + "materialNumberCustomer": [ + "MNR-7307-AU340474.002" + ], + "leadingRootCause": "strike", + "effect": "demand-reduction", + "notificationId": "urn:uuid:d8b6b4ca-ca9c-42d9-8a34-f62591a1c68a", + "relatedNotificationId": "urn:uuid:d8b6b4ca-ca9c-42d9-8a34-f62591a1c68a", + "sourceNotificationId": "urn:uuid:d8b6b4ca-ca9c-42d9-8a34-f62591b7d13c", + "text": "Capacity reduction due to ongoing strike.", + "expectedEndDateOfEffect": "2023-12-17T08:00:00+01:00", + "status": "open" +} +``` + +### 1.5 TERMINOLOGY + +> *This section is non-normative* + +*The following terms are especially relevant for the understanding of the standard:* + +| **Name** | **Description** | +| --- | --- | +| Aspect Model | An Aspect Model is a structured, machine-readable description of data. It utilizes the Turtle file format to serialize a Resource Description Framework (RDF) graph, that relates to a specific Aspect. It must follow the Semantic Aspect Meta Model (SAMM) guidelines, meaning it uses defined elements and rules from SAMM. Aspect Models help to clarify the meaning of data at runtime and should link to standardized Business Glossary terms, if available. | +| Bottleneck | A facility, function, department, or resource whose capacity is less than the demand placed upon it. For example, a bottleneck machine or work center exists where jobs are processed at a slower rate than they are demanded (Source: ASCM Supply Chain Dictionary, 17th edition). | +| Business Partner Number Legal Entity (BPNL) | A BPNL is a unique identifier for a company or partner within the Catena-X network. | +| Business Partner Number Site (BPNS) | A BPNS is a unique identifier for a specific location, such as a factory, within the Catena-X network. | +| Capacity | 1. The capability of a system to perform its expected function. 2. The capability of a worker, machine, work center, plant, or organization to produce output per time period. (Source: ASCM Supply Chain Dictionary, 17th edition) | +| Comment | A feature that allows two business partners to exchange messages about material demand and capacity, facilitating direct collaboration and quick issue resolution. | +| Comments | These are purely text-based exchanges without the transfer of documents or attachments. | +| Customer | A role within the *Supply Chain Disruption Notifications* process. Participating companies can have multiple roles at the same time. Customers provide demands to and receive capacities from suppliers. | +| Digital Twin | Based on [[CX-0002]](#61-normative-references) Standard a digital twin (DT) describes a digital representation of an asset sufficient to meet the requirements of a set of use cases. For detailed information please refer to [[CX-0002]](#61-normative-references) Digital Twins in Catena-X. | +| Material | The elements, constituents, or substances of which something is composed or can be made. Usually referred to by a material number. | +| (Material) demand | A need for a particular product or component. The demand could come from any number of sources (e.g., a customer order or forecast, an interplant requirement, a branch warehouse request for a service part, or the manufacturing of another product). At the finished goods level, demand data is usually different from sales data because demand does not necessarily result in sales (i.e., If there is no stock, there will be no sale (Source: ASCM Supply Chain Dictionary, 17th edition). Material demand may comprise multiple demand series by location and demand categories. When the term is written as one word (MaterialDemand), the term refers specifically to the respective aspect model. | +| Supplier | A role within the *Supply Chain Disruption Notifications* process. Participating companies can have multiple roles at the same time. Suppliers provide capacities to and receive demands from customers. | +| Surplus | A surplus is a situation in which an oversupply exists. | + +*Table 1: List of terminology helpful for understanding the standard* + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 RELEVANT PARTS OF THE STANDARD FOR SPECIFIC USE CASES + +> *This section is normative* + +### 2.1 SUPPLY CHAIN DISRUPTION NOTIFICATIONS + +#### 2.1.1 LIST OF STANDALONE STANDARDS + +The following Catena-X standards are prerequisite for the implementation of this standard and +therefore **MUST** be considered / implemented by the relevant parties specified in each of them. + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0001]](#61-normative-references) | EDC Discovery API | 1.0.2 | +| [[CX-0003]](#61-normative-references) | SAMM Aspect Meta Model | 1.1.0 | +| [[CX-0006]](#61-normative-references) | Registration and initial onboarding | 2.0.0 | +| [[CX-0010]](#61-normative-references) | Business Partner Number (BPN) | 2.0.0 | +| [[CX-0018]](#61-normative-references) | Dataspace Connectivity | 3.0.0 | +| [[CX-0126]](#61-normative-references) | Industry Core Part Type | 2.0.0 | + +*Table 2: List of mandatory standards* + +The usage of this standard **MAY** be complemented with the following Catena-X standards to further +extend the range of shortage prevention possibilities: + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [[CX-0118]](#61-normative-references) | Delivery Information Exchange | 2.0.0 | +| [[CX-0120]](#61-normative-references) | Short Term Material Demand Exchange | 2.0.0 | +| [[CX-0121]](#61-normative-references) | Planned Production Output Exchange | 2.0.0 | +| [[CX-0122]](#61-normative-references) | Item Stock Exchange | 2.0.0 | +| [[CX-0128]](#61-normative-references) | Demand and Capacity Management Data Exchange | 2.0.0 | +| [[CX-0145]](#61-normative-references) | Days of Supply Exchange | 1.0.0 | + +*Table 3: List of non-mandatory, but complementary standards* + +#### 2.1.2 DATA REQUIRED + +No additional data requirements. + +#### 2.1.3 ADDITIONAL REQUIREMENTS + +##### CONVENTIONS FOR USE CASE POLICY IN CONTEXT DATA EXCHANGE + +In alignment with our commitment to data sovereignty, a specific framework governing the utilization +of data within the Catena-X use cases has been outlined. A set of specific policies on data offering +and data usage level detail the conditions under which data may be accessed, shared, and used, +ensuring compliance with legal standards. + +For a comprehensive understanding of the rights, restrictions, and obligations associated with data +usage in the Catena-X ecosystem, we refer users to + +- the detailed ODRL policy repository [[CX-ODRL]](#62-non-normative-references). This document provides in-depth explanations of the + terms and conditions applied to data access and utilization, ensuring that all engagement with our data + is conducted responsibly and in accordance with established guidelines. +- the ODRL schema template. This defines how policies used for data sharing/usage should get defined. + Those schemas **MUST** be followed when providing services or apps for data sharing/consuming. + +###### ADDITIONAL DETAILS REGARDING ACCESS POLICIES + +A Data Provider may tie certain access authorizations ("Access Policies") to its data offers for +members of Catena-X and one or several Data Consumers. By limiting access to certain Participants, +Data Provider maintains control over its anti-trust obligations when sharing certain data. In +particular, Data Provider may apply Access Policies to restrict access to a particular data offer +for only one Participant identified by a specific business partner number. + +- Membership +- BPNL + +###### ADDITIONAL DETAILS REGARDING USAGE POLICIES + +In the context of data usage policies (“Usage Policies”), Participants and related services **MUST** use +the following policy rules: + +- Use Case Framework (“FrameworkAgreement”) +- at least one use case purpose (“UsagePurpose”) from the above mentioned ODRL policy repository. + +Additionally, respective usage policies **MAY** include the following policy rule: + +- Reference Contract (“ContractReference”). + +Details on namespaces and ODRL policy rule values to be used for the above-mentioned types are +provided via the ODRL policy repository [[CX-ODRL]](#62-non-normative-references). + +#### 2.1.4 DIGITAL TWINS AND SPECIFIC ASSET IDs + +This version of the document does not define any requirements for standardized integration and +governance of digital twins for a notification. *Supply Chain Disruption Notifications* do not rely +on Asset Administration Shell or Digital Twin APIs. This standard utilizes the Catena-X Material +Global Asset ID as an optional property in the DemandAndCapacityNotification aspect model, that +needs to be compliant to standard [[CX-0126]](#61-normative-references) Industry Core: Part Type. + +## 3 ASPECT MODELS + +> *This section is normative* + +### 3.1 ASPECT MODEL "Demand and Capacity Notification" + +#### 3.1.1 INTRODUCTION + +This section describes the DemandAndCapacityNotification semantic model used in the Catena-X +network. For the complete semantics and detailed description of its properties refer to the SAMM +model in [Chapter 3.1.5.1](#3151-rdf-turtle). + +Business partners that are exchanging (sending and receiving) *Demand and Capacity Notifications* +**MUST** implement the data model DemandAndCapacityNotification. + +Every data provider of DemandAndCapacityNotification **MUST** provide the data conformant to the +semantic model specified in this document. + +Every business application relying on DemandAndCapacityNotification **MUST** be able to consume +data conformant to the semantic model specified in this document. + +This semantic model **MUST** be made available in the central Semantic Hub. + +Data consumers and data provider **MUST** comply with the license of the semantic model defined in +[Chapter 3.1.3](#313-license). + +In the Catena-X data space DemandAndCapacityNotification **MUST** be exchanged via a connector +conformant to [[CX-0018]](#61-normative-references). + +The JSON Payload of data providers **MUST** be conformant to the JSON Schema as specified in this +document. + +The characteristics BPNL and BPNS **MUST** be used according to the standard [[CX-0010]](#61-normative-references). + +#### 3.1.2 SPECIFICATIONS ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the +"semantic-driven workflow" to create a submodel template specification [[SMT]](#62-non-normative-references). + +This aspect model is written in SAMM 2.1.0 as a modeling language conformant to [[CX-0003]](#61-normative-references) as +input for the semantic driven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to [[CX-0003]](#61-normative-references). + +#### 3.1.3 LICENSE + +This Catena-X data model is made available under the terms of the Creative Commons Attribution 4.0 +International (CC-BY-4.0) license, which is available at Creative Commons. + +#### 3.1.4 IDENTIFIER OF SEMANTIC MODEL + +The semantic model has the unique identifier + +> `urn:samm:io.catenax.demand_and_capacity_notification:2.0.0` + +This identifier **MUST** be used by the data provider to define the semantics of the data being transferred. + +#### 3.1.5 FORMATS OF SEMANTIC MODEL + +##### 3.1.5.1 RDF TURTLE + +The RDF turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional +file formats and serializations. It can be found under the following link: + +> [https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.demand_and_capacity_notification/2.0.0/DemandAndCapacityNotification.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.demand_and_capacity_notification/2.0.0/DemandAndCapacityNotification.ttl) + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation of +other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel Template +or a HTML documentation. + +##### 3.1.5.2 JSON SCHEMA + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only payload +of the Asset Administration Shell for the API operation *"GetSubmodel"*. + +##### 3.1.5.3 AASX + +An AASX file **MUST** be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to [[SMT]](#62-non-normative-references). + +## 4 APPLICATION PROGRAMMING INTERFACES + +> *This section is normative* + +### 4.1 "DEMAND AND CAPACITY NOTIFICATION" API + +The "DemandAndCapacityNotification API" defined in this section enables the exchange of the *Demand and Capacity Notifications* between Catena-X participants in an interoperable manner. *Figure 1* shows +a high level overview of the intended data exchange flow without including a Connector. In practice, +the data must be exchanged via a Connector as described in [Chapter 3.1.1](#311-introduction). + +![Demand and Capacity Notification API overview](./assets/figure_1.svg) +*Figure 1: Demand and Capacity Notification API overview* + +The API relies on synchronous communication between the involved parties. + +1. The data exchange is initiated by the data provider. +2. The data provider is submitting a request to the data consumer. +3. The data consumer accepts a valid request and confirms the successful receipt. + +The lifecycle of a DemandAndCapacityNotification is defined by the set of states shown in *Figure 2*. +The data provider, i.e. the initiator of the *Demand and Capacity Notification*, must use the status +"open" when opening a thread for the first time. + +To mark a notification as resolved, the data provider **MUST** send the updated notification, where + +- the `notificationId` **MUST** be equal to the notification ID of the notification that should be updated and +- the status **MUST** be equal to "resolved". + +Refer to [Chapter 5](#5-processes) for the handling of notification updates. + +![States of the Demand and Capacity Notifications](./assets/figure_2.svg) +*Figure 2: States of the Demand and Capacity Notifications* + +#### 4.1.1 PRECONDITIONS AND DEPENDENCIES + +To use this standard the participants **MUST** have an existing business relationship. + +To participate in the Catena-X dataspace, both the data consumer and the data provider **MUST** be registered and onboarded as defined in [[CX-006]](#61-normative-references). + +A dataspace connector conformant to [[CX-0018]](#61-normative-references) **MUST** be used to make the API available to network participants. + +The API endpoint defined in [Chapter 4.1.2.1](#4121-api-endpoints--resources) **MUST** therefore be offered as data asset / contract offer as defined in [[CX-0018]](#61-normative-references). + +#### 4.1.2 API SPECIFICATION + +##### 4.1.2.1 API ENDPOINTS & RESOURCES + +Catena-X participants interested in exchanging *Demand and Capacity Notifications* **MUST** define +and implement a single endpoint supporting the HTTP POST request. The structure of the endpoint +**MAY** be freely chosen. The address of the endpoint **MUST** be provided as part of the Data Asset +defined in [Chapter 4.1.3](#413-data-asset-structure). + +##### 4.1.2.2 DATA EXCHANGE + +The DemandAndCapacityNotification data **MUST** be sent from the sender to the receiver using an +HTTP POST request. The data format described here **MUST** be followed for the exchange of the +*Demand and Capacity Notification*. + +The endpoints are defined in the table below based on their role in the data exchange process. + +>**Note:** Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +| **Role** | **Endpoint** | **Route** | **REQUIRED** | **HTTP Method** | **Purpose** | +| --- | --- | --- | --- | --- | --- | +| Receiver | Request Endpoint | `{{DEMAND-AND-CAPACITY-NOTIFICATION-API-ENDPOINT}}` | Yes | **POST** | This endpoint receives the DemandAndCapacityNotification to the sender requests. | + +*Table 4: Endpoint in the data exchange process* + +The serialized JSON **MUST NOT** be larger than 15 MiB in size. + +The "Demand and Capacity Notification API" endpoint **MUST** be implemented by all Catena-X +participants who wish to receive DemandAndCapacityNotification data. Senders **MUST** be able to +send DemandAndCapacityNotification object to their receivers. + +The data payload itself **MUST** be a valid JSON string. + +All attributes marked as *mandatory* in the aspect model standard **MUST** be included in the dataset. Attributes marked as *optional* **MAY** be included in the data set. + +The usage of the attributes in the data model **MUST** follow the attribute descriptions of the respective aspect model and the definitions in [Chapter 3.1](#62-non-normative-references). + +While some attributes are technically a string, not any string is valid. For example, each entry of +affectedSitesSender **MUST** be formatted as a BPNS. In that case, the aspect model will have +constraints describing how a valid value should look like. + +When consuming a payload, that contains unknown properties not described within the data model but +is otherwise correct, those properties **MUST** be ignored. + +**Message Header** + +> **Note:** This is not the HTTP Header but rather part of the HTTP Body. + +When exchanging data described in this chapter, the POST request payload **MUST** be structured as follows: + +```json +{ + "header": , + "content": { + "demandAndCapacityNotification": + } +} +``` + +This format keeps the header, which includes metadata about the message, separated from the content, +which includes the actual data being exchanged. + +The master reference for generating additional file formats and serializations is the RDF turtle file, +which is an instance of the Semantic Aspect Meta Model. The RDF turtle file for the `messageHeaderObject` +is defined in a centralized shared aspect model and can be accessed at the following URL: + +>[https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shared.message\_header/3.0.0/MessageHeaderAspect.ttl](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shared.message_header/3.0.0/MessageHeaderAspect.ttl) + +The RDF turtle file provides detailed description on how to use the message header. + +The following table lists all fields of the message header and how they are used. + +| **Field** | **REQUIRED** | **Purpose** | **Datatype** | **Example value** | +| --- | --- | --- | --- | --- | +| messageId | Yes | Unique ID identifying the message. The purpose of the ID is to uniquely identify a single message, therefore it **MUST NOT** be reused. This ID must not be confused with the notification id within the payload and thus, should be different. | UUID v4 [RFC4122] | `urn:uuid:375e75f0-913e-4b71-a96c-366fc8f6bf8f` | +| relatedMessageId | No | For the "Demand and Capacity Notification" this information **MUST NOT** be set. Correlations of notifications is handled within the payload as described in [Chapter 5](#5-processes). | UUID v4 [RFC4122] | | +| context | Yes | This field **MUST** contain the namespace of the Demand and Capacity Notification API that is sent within the content section of the message. The version is not specified according to the SAMM version of the DemandAndCapacityNotification SAMM model in use. | URI | `CX-DemandAndCapacityNotification:1.0` | +| version | Yes | This field **MUST** specify the version of the header's aspect model that has been used to create the header. | Version of the shared aspect model MessageHeader | `3.0.0` | +| senderBpn | Yes | The business partner number (BPNL) of the responding party. | BPNL according to [[CX-0010]](#61-normative-references) | `BPNL7588787849VQ` | +| receiverBpn | Yes | The business partner number (BPNL) of the receiving party. | BPNL according to [[CX-0010]](#61-normative-references) | `BPNL6666787765VQ` | +| sentDateTime | Yes | The date and time including time zone offset on which the request has been created. | [[ISO8601]](#62-non-normative-references) with time zone | `2023-06-19T21:24:00+07:00` | + +*Table 5: Message header fields used in the Demand and Capacity Notification API* + +**Message Content** + +The message content consists of a single `demandAndCapacityNotifcation` object containing a single +JSON-serialization of the DemandAndCapacityDemand SAMM model (see [Chapter 3](#3-aspect-models)) following the rules +defined in [Chapter 5](#5-processes). + +**Message Example** + +The following JSON provides an example of the value-only serialization of the *Supply Chain Disruption Notification* aspect model for a sample notification including a message header. + +```json +{ + "header": { + "senderBpn": "BPNL7588787849VQ", + "context": "CX-DemandAndCapacityNotification:1.0", + "messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", + "receiverBpn": "BPNL6666787765VQ", + "sentDateTime": "2023-06-19T21:24:00+07:00", + "version": "3.0.0" + }, + "content": { + "demandAndCapacityNotification": { + "affectedSitesSender": [ + "BPNS7588787849VQ" + ], + "affectedSitesRecipient": [ + "BPNS6666787765VQ" + ], + "materialNumberSupplier": [ + "MNR-8101-ID146955.001" + ], + "contentChangedAt": "2023-12-13T15:00:00+01:00", + "startDateOfEffect": "2023-12-13T15:00:00+01:00", + "relatedNotificationId": "urn:uuid:d05cef4a-b692-45bf-87cc-eda2d84e4c04", + "materialNumberCustomer": [ + "MNR-7307-AU340474.002" + ], + "leadingRootCause": "strike", + "materialGlobalAssetId": [ + "urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df" + ], + "effect": "demand-reduction", + "notificationId": "urn:uuid:d9452f24-3bf3-4134-b3eb-68858f1b2362", + "text": "Capacity reduction due to ongoing strike.", + "expectedEndDateOfEffect": "2023-12-17T08:00:00+01:00", + "sourceNotificationId": "urn:uuid:c69cb3e4-16ad-43c3-82b9-0deac75ecf9e", + "status": "resolved" + } + } +} +``` + +##### 4.1.2.3 UUID generation and handling + +When exchanging DemandAndCapacityNotification data, the usage of UUIDv4 is **REQUIRED** in order to +reduce the probability of collision as well as to eliminate certain attack vectors. For technical +purposes the UUIDv4 **MUST** be treated as unique within the supplier-customer relationship. + +The UUIDv4 **MUST** be generated according to [RFC4122](#62-non-normative-references). + +##### 4.1.2.5 AVAILABLE DATA TYPES + +The API **MUST** use JSON as the payload is transported via HTTPS. + +#### 4.1.3 DATA ASSET STRUCTURE + +The endpoints introduced in [Chapter 4.1.2](#412-api-specification) **MUST NOT** be directly called neither from a provider +nor from a consumer. Rather, these **MUST** be called via a connector conformant to [[CX-0018]](#61-normative-references). +Therefore, the endpoints **MUST** be offered as data assets. To make these assets easily identifiable +in the connector's catalog, each asset **MUST** be configured with a set of properties as described in +the corresponding sections below. + +The API version described in this standard **MUST** be published in the property +[https://w3id.org/catenax/ontology/common#version](https://w3id.org/catenax/ontology/common#version) +as version `1.0` in the asset. The requester of an asset **MUST** be able to handle multiple assets +for this endpoint, being differentiated only by the version. The requester **SHOULD** choose the +asset with the highest compatible version number implemented by themselves. If the requester cannot +find a compatible version with their own, the requester **MUST** terminate the data transfer. + +The following table provides an overview of the data assets that the parties **MUST** offer to be +able to provision and/or consume DemandAndCapacityNotification data. + +| **Party** | **REQUIRED** | **Asset** | **Purpose** | +| --- | --- | --- | --- | +| Consumer | Yes | "Demand and Capacity Notification API" | Allows a provider to submit a *Demand and Capacity Notification*. | + +*Table 6: Data assets* + +**Data Asset Structure for "Demand and Capacity Notification API Endpoint"** + +To receive DemandAndCapacityNotification data, the receiver **MUST** register a data asset specifying +the address of the "Demand and Capacity Notification API" Endpoint described in [Chapter 4.1.2](#412-api-specification). + +The data asset **MUST** be configured with the set of properties as defined in the table below. + +| **Property** | **Purpose** | **Usage & Constraints** | +| --- | --- | --- | +| ***@id*** | Identifier of the asset. | The asset ID **MUST** be unique and therefore **MUST NOT** be reused elsewhere. | +| properties.**http://purl.org/dc/terms/type** | Defines the "Demand and Capacity Notification API" endpoint according to the Catena-X taxonomy. | **MUST** be set to `{"@id": "https://w3id.org/catenax/taxonomy#DemandAndCapacityNotificationApi"}` to allow filtering the data assets catalog for the respective "Demand and Capacity Notification API". | +| properties.**https://w3id.org/catenax/ontology/common#version** | The version of the standard defining the implemented API. | **MUST** correspond to the version of the standard defining the "Demand and Capacity Notification API". The value **MUST** be set to `"1.0"` for APIs implementing this standard. | +| dataAddress.properties. **@type** | Type of the DataAddress node. | **MUST** be set to `"DataAddress"`. | +| dataAddress.properties. ***baseUrl*** | Defines the HTTPS endpoint of the corresponding "Demand and Capacity Notification API" endpoint. | The `{{DEMAND_AND_CAPACITY_NOTIFICATION_REQUEST_ENDPOINT}}` refers to an URL under which the API endpoint is available. HTTPS transport protocol **MUST** be used. | +| dataAddress.properties. ***proxyBody*** | Defines whether the endpoint allows to proxy the HTTPS body. | **MUST** be set to `"true"` to allow the API endpoint to receive a HTTPS body via the HTTPS request. | +| dataAddress.properties. ***proxyMethod*** | Defines whether the endpoint allows to proxy the HTTPS method. | **MUST** be set to `"true"` to allow the API endpoint to receive POST requests. | +| dataAddress.properties. ***type*** | Defines the type of data plane extension handling the data exchange. | **MUST** be set to `"HttpData"` to provide an API via an HTTPS proxy endpoint. | + +*Table 7: Data assets request properties* + +When searching the Catalog of a provider, a consumer **MUST** use the following properties AND their + values to identify the Data Asset specifying "Demand and Capacity Notification API". In the connector + Data Asset descriptions the API version valid for this standard is mentioned for the property + [https://w3id.org/catenax/ontology/common#version](https://w3id.org/catenax/ontology/common#version). The requester of a Data Asset **MUST** + be able to handle multiple Data Asset for this endpoint, being differentiated only by the version. + The requester **SHOULD** choose the Data Asset set with the highest compatible version number implemented + by themselves. If the requester cannot find a compatible version with their own, the requester **MUST** + terminate the data transfer. + +| **Property** | **Value** | +| --- | --- | +| properties.***dct:type*** | `{"@id": "https://w3id.org/catenax/taxonomy#DemandAndCapacityNotificationApi"}` | + +*Table 8: Data assets request properties values* + +Because the data asset reflects the existing contractual relationship between a customer and its suppliers, +only one data asset with the aforementioned combination of properties AND their values **MUST** be visible +to the data consumer at any time to avoid ambiguity. + +An example Data Asset definition is given below. + +> Note: Expressions in double curly braces \{\{\}\} must be substituted with a corresponding value. + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "cx-taxo": "https://w3id.org/catenax/taxonomy#", + "cx-common": "https://w3id.org/catenax/ontology/common#", + "dct": "https://purl.org/dc/terms/" + }, + "@id": "{{DEMAND_AND_CAPACITY_NOTIFICATION_API_ASSET_ID}}", + "properties": { + "dct:type": { + "@id": "cx-taxo:DemandAndCapacityNotificationApi" + }, + "cx-common:version": "1.0", + "description": "Demand and Capacity Notification API Endpoint" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "proxyBody": "true", + "proxyMethod": "true", + "baseUrl": "{{DEMAND_AND_CAPACITY_NOTIFICATION_API_ENDPOINT}}", + "method": "POST", + "contentType": "application/json" + } +} +``` + +#### 4.1.4 ERROR HANDLING + +Every API endpoint defined in [Chapter 4.1.2](#412-api-specification) **MUST** respond to incoming requests with HTTP status codes +as described in [[RFC9110]](#62-non-normative-references). All of the following HTTP status codes, except for codes `200` and `201`, +**MUST** be interpreted as failures. Therefore, it may be sufficient for a business application to +simply check if the status code is `200` or `201` or not. If not, the request failed. The status codes +for each endpoint are defined in the following sections. + +**HTTP Codes for Demand and Capacity Notification Response Endpoint** + +| **Status Code** | **Description** | **Usage** | +| --- | --- | --- | +| `400` | Response body malformed or validation failed as defined in [Chapter 4.1.5](#415-validating-payload) | When the HTTP Body is not matching the API description, the consumer **MUST** respond with error code `400` | +| `401` | Not authorized | When the authorization of the response fails, the consumer **MUST** respond with error code `401` | +| `404` | Endpoint not found | When the HTTP path is not available, the consumer **MUST** respond with error code `404` | +| `405` | Method not allowed | In case the HTTP call is not a POST, the provider **MUST** respond with error code `405` | +| `503` | Service unavailable | The server is not ready to handle the request | + +*Table 9: Request error handling* + +Further status codes may be included in a later revision of this standard. The ability to send and +receive one status code per sent or received list item might be included in a later revision of this +standard. + +##### 4.1.5 VALIDATING PAYLOAD + +The following tables are supposed to answer questions regarding what business logic **MUST** be +executed when receiving a DemandAndCapacityNotification which has been formed in a specific way. + +The order of rules is indicated by the 'Number' row. The rules **MUST** be executed in exactly this +order, starting from the lowest number. + +The first rule that matches **MUST** be executed. All other rules **MUST** be ignored. + +'value' indicates the actual value written in quotation marks and without any specific formatting +(e.g. italic). + +Valid value indicates that the value is valid according to aspect model, API and process. + +Invalid value indicates that the value is invalid according to aspect model, API and process. + +Any value indicates that the value can by anything, valid or not. + +A whitespace or an empty cell indicates that for this specific rule that row is not applicable. + +| Number | 1 | | +| --- | --- | --- | +| Properties | | | +| Meta Properties | Any property | *invalid value* | +| | All other properties | *Any value* | +| Actions | Business Logic | Ignore received values | +| | Return Code | `400` - Bad Request | + +| Number | 2 | | +| --- | --- | --- | +| Properties | `affectedSitesSender` | One or more BPNS do not match to the sending Connector's registered BPNS | +| Meta Properties | Any property | | +| | All other properties | *Any value* | +| Actions | Business Logic | Ignore received values | +| | Return Code | `400` - Bad Request | + +| Number | 3 | | +| --- | --- | --- | +| Properties | `affectedSitesRecipient` | One or more BPNS do not match BPNS that I am responsible for | +| Meta Properties | Any property | | +| | All other properties | *Any value* | +| Actions | Business Logic | Ignore received values | +| | Return Code | `400` - Bad Request | + +| Number | 4 | | +| --- | --- | --- | +| Properties | `notificationId` | Valid UUID which matches a received `notificationId` of the same partner | +| | `contentChangedAt` | Valid Timestamp which is older than or equal to the Timestamp of `contentChangedAt` from the previously received notification. | +| Meta Properties | Any property | | +| | `senderBpn` | Not equal to the `senderBpn` which originally sent the notification with this notificationId | +| | All other properties | *Valid value* | +| Actions | Business Logic | Ignore received values due to old content | +| | Return Code | `400` - Bad Request | + +| Number | 5 | | +| --- | --- | --- | +| Properties | `notificationId` | Valid UUID which matches a received notificationId of the same partner | +| | `status` | Equal to "resolved" | +| Meta Properties | Any property | | +| | `senderBpn` | Not equal to the `senderBpn` which originally sent the notification with this notificationId | +| | All other properties | *Valid value* | +| Actions | Business Logic | Ignore received values | +| | Return Code | `400` - Bad Request | + +| Number | 6 | | +| --- | --- | --- | +| Properties | `notificationId` | Valid UUID which matches a received `notificationId` of the same partner | +| | `contentChangedAt` | Valid Timestamp which is newer than the Timestamp of `contentChangedAt` from the previously received notification. | +| Meta Properties | Any property | | +| | All other properties | *Valid value* | +| Actions | Business Logic | Overwrite all existing values with received values | +| | Return Code | `200` - OK | + +| Number | 7 | | +| --- | --- | --- | +| Properties | `notificationId` | Valid UUID which does not match any received `notificationId` of the same partner | +| Meta Properties | Any property | | +| | All other properties | *Valid value* | +| Actions | Business Logic | Accept new notification | +| | Return Code | `200` - OK | + +## 5 PROCESSES + +> *This section is normative* + +### 5.1 SUPPLY CHAIN DISRUPTION NOTIFICATION PROCESS + +*Supply Chain Disruption Notifications* (further called "notification(s)" in [Chapter 5](#5-processes)) +are a collaboration functionality business partners **MAY** use to interact with each other. Focus +is to quickly inform the relevant business partners in the supply chain about an upcoming +disruption. Notifications functionality **SHOULD** be used by any value chain partner, if the +expected impact goes beyond the regular one-to-one business relationship between one-up and one-down +and might therefore be relevant for part or even the whole supply chain network. Typical cases in +real business are force major events (e.g. natural disaster, production incidents, wars, pandemics +etc.). Even though a notification **MUST** be always sent between one-up and one-down partner, the +intention is, that the recipient will further forward the adjusted notification up or down the +supply chain. If, after internal evaluation, the recipient decides to inform further business +partners, the notification **MUST** be modified and cannot simply be identically forwarded. This +results into a new notification ID. + +Therefore a partner **MUST** be able to receive and process notifications. Being able to send +notifications is highly **RECOMMENDED** in order to participate in a collaborative environment and +make full use of the notifications feature. Furthermore, notifications **MUST** work in both +directions (up- and downstream). In case a business partner needs to send a notification up- and +downstream the supply chain at the same time, two individual notifications **MUST** be sent +resulting into individual notification IDs (see Figure 4). + +The notification consists of a message header (see Table 5) and a notification payload (see Table 10) +which **MUST** be filled by the sender of the notification and are explained in the mentioned +tables. Mandatory (M) fields **MUST** be filled to correctly send a notification and optional (O) +fields **MAY** be filled by the sender. Once completely and correctly filled, the notification can +be shared with one-up or one-down business partners. Each partner receiving a notification **MAY** +decide, after having evaluated the impact, if they need to inform their potentially affected +business partners up- or downstream the supply chain (depending on the notification direction) +following the same process logic as written above. Each new notification **MUST** receive its +individual notification ID and a sender of a notification **MAY** link a reference to a previously +sent notification ID or source notification ID. Only the referred notification ID itself is added to +the notification (neither content nor other information e.g. at which tier-level the incident +started). If several value chain partners e.g. refer to the same initially shared notification ID +within their notification, a recipient is able to understand the impact of the problem. The sender +of the notification **MUST** respect data privacy laws and **MUST** follow antitrust rules. Update +of further objects (e.g. MaterialDemand) is not directly part of the notifications functionality as +this happens in separate collaboration between one-up and one-down (e.g. comment function). Updating +a notification content results into an update of the ContentChangedAt using the same notification +ID. With that information the recipient is able to identify when the content of the original +notification was updated. Resolving a notification **MUST** be done only by the sender and this +update of the notification follows the same logic via new ContentChangedAt timestamp as described +before. + +**Demand and Capacity Notification Payload Description** + +| **Field name / Structure** | **Mandatory** / **Optional**|**Data type**|**Description**|**Example** | +| --- | --- | --- | --- | --- | +| **Notification ID** | M | UUID | Unique ID identifying the notification. | `urn:uuid:d9452f24-3bf3-4134-b3eb-68858f1b2362` | +| **Affected Sites Sender** | O | Collection - BPNS - String | The affected Business Partner site Numbers of the sender.It is RECOMMENDED to send the senderBpns. It **MUST** be possible to select multiple senderBpns. | `BPNS7588787849VQ` | +| **Affected Sites Recipient** | O | Collection - BPNS - String | The affected Business Partner site Numbers of the recipient.It is RECOMMENDED to send the recipient Bpns. It **MUST** be possible to select multiple recipient BPNS. | `BPNS6666787765VQ` | +| **Leading Root Cause** | M | Enumeration | Possible values:
    - strike
    - natural disaster
    - production incident
    - pandemic / epidemic
    - logistics disruption
    - war
    - other | `strike` | +| **Effect** | M | Enumeration | Notification Category / ImpactFrom a business perspective, demand or capacity reduction are the most relevant values in connection with above mentioned root causes. For technical completeness demand or capacity increase are also added to the value list. | `demand-reduction`, `capacity-reduction`, `capacity-increase`, `demand-increase` | +| **Text** | O | String | Free text description for notification (max. 4000 characters) | `"HelloWorld"` | +| **Material Number Customer** | O | Collection - ID - String | If the customer is the sender to send Customer Material number is RECOMMENDED. It **MUST** be possible to send n customer material numbers. | `MNR-7307-AU340474.002` | +| **Material Number Supplier** | O | Collection - ID - String | If the supplier is the sender sending supplier material number is RECOMMENDED. It **MUST** be possible to send n supplier material numbers. | `MNR-8101-ID146955.001` | +| **Material Global Asset ID** | O | Collection - ID - String | MaterialGlobalAssetID references a digital twin. Via a digital twin a recipient is able to identify the own affected material numbers as the digital twin connects sender and recipient material numbers. If a digital twin is available it is RECOMMENDED only exchanging the digital twin material number. | `urn:uuid:48878d48-6f1d-47f5-8ded-a441d0d879df` | +| **Start Date of Effect** | M | Timestamp | Expected start date of the impact **MUST** be shared by the sender of the message.This also applies to cases where the sending of the message and start date of the effect differ from each other. | `2023-06-05T08:00:00+02:00` | +| **Expected End Date of Effect** | O | Timestamp | Expected end date of the impact **MAY** be mentioned by the sender of the notification. | `2023-06-19T08:00:00+02:00` | +| **Status** | M | Enumeration | Notification status | `"open"`, `"resolved"` | +| **Content Changed At** | M | Timestamp | Time where any property of the notification was updated the last time. | `2023-06-19T08:00:00+02:00` | +| **Related Notification ID** | O | UUID | Unique ID identifying a previously received notification triggering the exchange of the current notification. | `urn:uuid:d05cef4a-b692-45bf-87cc-eda2d84e4c04` | +| **Source Notification ID** | O | UUID | Unique ID identifying a source notification related to the current one. | `urn:uuid:c69cb3e4-16ad-43c3-82b9-0deac75ecf9e` | + +*Table 10: Demand and Capacity Notification Payload Description* + +### 5.2 ACTORS & ROLES + +| **Actors** | **Description** | +| --- | --- | +| Sender | The sender is the author of the notification. The sender is responsible to properly fill all necessary data fields and send the notification to its direct business partner (one-up or one-down). This means the sender acts as data provider within the notifications process and is sharing the notification with its direct business partners (one-up or one-down). Customer and supplier can both act as the sender of the notification. | +| Recipient | The recipient receives a notification from its direct business partner (one-up or one-down). The recipient needs to check the impact and might inform its further business partners up- or downstream the value chain. This means the recipient acts as a data consumer within the notifications process as the recipient is receiving the notification from its direct business partners (one-up or one-down). Customer and supplier can both act as the recipient of a notification. | +| Business application provider | The business application provider provides and operates an application/tool which enables the notifications process and follows core business logic, data model and API as described in this standard document. | + +*Table 11: Overview of Actors & Roles* + +### 5.3 PROCESS REPRESENTATION + +![Visualization Notifications Process I](./assets/figure_3.svg) +*Figure 3: Visualization Notifications Process I* + +![Visualization Notifications Process II](./assets/figure_4.svg) +*Figure 4: Visualization Notifications Process II* + +## 6 REFERENCES + +### 6.1 NORMATIVE REFERENCES + +> *This section is normative* + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [CX-0001] | EDC Discovery API | 1.0.2 | +| [CX-0003] | SAMM Aspect Meta Model | 1.1.0 | +| [CX-0006] | Registration and initial onboarding | 2.0.0 | +| [CX-0010] | Business Partner Number (BPN) | 2.0.0 | +| [CX-0018] | Dataspace Connectivity | 3.0.0 | +| [CX-0126] | Industry Core Part Type | 2.0.0 | + +### 6.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +| **Number** | **Standard** | **Version** | +| --- | --- | --- | +| [CX-0118] | Delivery Information Exchange | 2.0.0 | +| [CX-0120] | Short-term Material Demand Exchange | 2.0.0 | +| [CX-0121] | Planned Production Output Exchange | 2.0.0 | +| [CX-0122] | Item Stock Exchange | 2.0.0 | +| [CX-0128] | Demand and Capacity Management Data Exchange | 2.0.0 | +| [CX-0145] | Days of Supply Exchange | 1.0.0 | +| [ISO8601] | ISO 8601: Date and time format | | +| [RFC2119] | Bradner, S. Key words for use in RFCs to Indicate Requirement Levels. Available online: https://datatracker.ietf.org/doc/html/rfc2119|| +| [RFC4122] | A Universally Unique Identifier (UUID) URN Namespace (https://www.rfc-editor.org/rfc/rfc4122) || +| [RFC8174] | Leiba, B. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. Available online: https://datatracker.ietf.org/doc/html/rfc8174 || +| [RFC9110] | HTTP Semantics (https://www.rfc-editor.org/rfc/rfc9110) || +| [CX-ODRL] | Catena-X ODRL Profile repository: https://github.com/catenax-eV/cx-odrl-profile | +| [SMT] | How to create a submodel template specification. Guideline. Download from: https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf || + +### 6.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## ANNEXES + +### FIGURES + +*This section is non-normative* + +| **Figure** | **Name** | **Chapter** | +| --- | --- | --- | +| Figure 1 | *Demand and Capacity Notification API overview* | [4.1](#41-demand-and-capacity-notification-api) | +| Figure 2 | *States of the* Demand and Capacity Notifications | [4.1](#41-demand-and-capacity-notification-api) | +| Figure 3 | *Visualization Notifications Process I* | [5.3](#53-process-representation) | +| Figure 4 | *Visualization Notifications Process II* | [5.3](#53-process-representation) | + +*Table 14: List of Figures* + +### TABLES + +*This section is non-normative* + +| **Table** | **Name** | **Chapter** | +| --- | --- | --- | +| Table 1 | *List of terminology helpful for understanding the standard* | [1.5](#15-terminology) | +| Table 2 | *List of mandatory standards* | [2.1.1](#211-list-of-standalone-standards) | +| Table 3 | *List of* *non-mandatory, but* *complementary standards* | [2.1.1](#211-list-of-standalone-standards) | +| Table 4 | *Endpoint in the data exchange process* | [4.1.2.2](#4122-data-exchange) | +| Table 5 | *Message header fields used in the Demand and Capacity Notification API* | [4.1.2.2](#4122-data-exchange) | +| Table 6 | *Data assets* | [4.1.3](#413-data-asset-structure) | +| Table 7 | *Data assets request properties* | [4.1.3](#413-data-asset-structure) | +| Table 8 | *Data assets request properties values* | [4.1.3](#413-data-asset-structure) | +| Table 9 | *Request error handling* | [4.1.4](#414-error-handling) | +| Table 10 | *Demand and Capacity Notification Payload Description* | [5.1](#51-supply-chain-disruption-notification-process) | +| Table 11 | *Overview of Actors & Roles* | [5.2](#52-actors--roles) | +| Table 12 | *List of normative standards* | [6.1](#61-normative-references) | +| Table 13 | *List of non-normative standards* | [6.2](#62-non-normative-references) | +| Table 14 | *List if Figures* | [Annexes](#annexes) | +| Table 15 | *List of Tables* | [Annexes](#annexes) | + +*Table 15: List of Tables* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_1.puml b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_1.puml new file mode 100644 index 000000000..8260b67fa --- /dev/null +++ b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_1.puml @@ -0,0 +1,17 @@ +@startuml Figure_1 +autonumber +skinparam sequenceMessageAlign center + +box "Data Consumer" +participant "Business\nApplication" as app_cons +end box + +box "Data Provider" +participant "Business\nApplication" as app_prov +end box + + +app_cons <- app_prov: Send DemandAndCapacityNotification +return Accepted + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_1.svg b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_1.svg new file mode 100644 index 000000000..886e825e4 --- /dev/null +++ b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_1.svg @@ -0,0 +1,27 @@ +Data ConsumerData ProviderBusinessApplicationBusinessApplicationBusinessApplicationBusinessApplication1Send DemandAndCapacityNotification2Accepted \ No newline at end of file diff --git a/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_2.puml b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_2.puml new file mode 100644 index 000000000..6717f58e8 --- /dev/null +++ b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_2.puml @@ -0,0 +1,10 @@ +@startuml Figure_2 + +Open : The Demand and Capacity Notification was received by the Consumer and should be considered as an active event. +Resolved : The Demand and Capacity Notification was declared as resolved by the data provider of the Notification. + +[*] --> Open : Data provider submitted the Demand and Capacity Notification with the status "open" +Open --> Resolved : Data provider declared that the Demand and Capacity Notification should be closed +Resolved --> [*] + +@enduml \ No newline at end of file diff --git a/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_2.svg b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_2.svg new file mode 100644 index 000000000..66cd79270 --- /dev/null +++ b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_2.svg @@ -0,0 +1,23 @@ +OpenThe Demand and Capacity Notification was received by the Consumer and should be considered as an active event.ResolvedThe Demand and Capacity Notification was declared as resolved by the data provider of the Notification.Data provider submitted the Demand and Capacity Notification with the status "open"Data provider declared that the Demand and Capacity Notification should be closed \ No newline at end of file diff --git a/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_3.svg b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_3.svg new file mode 100644 index 000000000..162b6ef7c --- /dev/null +++ b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_3.svg @@ -0,0 +1 @@ +OEMTier1Tier2Tier3Tier4NotificationNotificationSource NotificationdirectionMessage ID: 1NotificationID: 10Recipient: BPNL2Sender: BPNL1Root Cause: naturaldisasterEffect: CapacitydecreaseText: Earthquakein Country AMessage ID: 3NotificationID: 20Recipient: BPNL3Sender: BPNL2RelatedNotificationID: 10Root Cause: OtherEffect: CapacitydecreaseMessage ID: 4NotificationID: 30Recipient: BPNL5Sender: BPNL3RelatedNotificationID: 20Source NotificationID: 10Effect: CapacitydecreaseMessage ID: 5NotificationID: 40Recipient: BPNL6Sender: BPNL5RelatedNotificationID: 30Source NotificationID: 10Effect: CapacitydecreaseMessage ID: 2NotificationID: 20Recipient: BPNL4Sender: BPNL2RelatedNotificationID: 10Root Cause: OtherEffect: Capacitydecrease \ No newline at end of file diff --git a/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_4.svg b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_4.svg new file mode 100644 index 000000000..d6851af0d --- /dev/null +++ b/docs/standards/CX-0146-SupplyChainDisruptionNotifications/assets/figure_4.svg @@ -0,0 +1 @@ +OEMTier1Tier2Tier3Tier4Message ID: 3NotificationID: 30Recipient: BPNL4Sender: BPNL2RelatedNotificationID: 10Root Cause: productionincidentEffect: CapacitydecreaseMessage ID: 1NotificationID: 10Recipient: BPNL2Sender: BPNL1Root Cause: productionincidentEffect: CapacitydecreaseText: MachineA breakdównMessage ID: 2NotificationID: 20Recipient: BPNL3Sender: BPNL1Root Cause: productionincidentEffect: Demand decreaseText: MachineA breakdownMessage ID: 4NotificationID: 40Recipient: BPNL5Sender: BPNL3RelatedNotificationID: 20Root Cause: OtherEffect: Demand decreaseNotificationNotificationSource Notificationdirection \ No newline at end of file diff --git a/docs/standards/CX-0149-Dataspaceidentityandidentification/CX-0149-Dataspaceidentityandidentification.md b/docs/standards/CX-0149-Dataspaceidentityandidentification/CX-0149-Dataspaceidentityandidentification.md new file mode 100644 index 000000000..6d783dd39 --- /dev/null +++ b/docs/standards/CX-0149-Dataspaceidentityandidentification/CX-0149-Dataspaceidentityandidentification.md @@ -0,0 +1,469 @@ +# CX-0149 Verified Company Identity v1.0.0 + +## COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD + +- This document combines the previous standards `CX - 0016 Company Attribute Verification v1.1.0` and `CX - 0017 Company Role by the Connector v1.0.1` including all needed information for the identification of a participant and the Dataspace clients acting on behalf of them +- Introducing the *Identity and Trust Protocol (IATP)* used within the identity presentation flow +- Introducing an API specification for the *Creation of Participants Wallet* as a foundation for the usage of multiple Wallet providers. + +## ABSTRACT + +This document specifies the requirements for the identification of Dataspace participants and the Dataspace clients acting on behalf of the participants for the enablement of a controlled and controllable data exchange. The requirements and prerequisites described here serve both data sovereignty and interoperability. + +## 1. INTRODUCTION + +Self-sovereign identity (SSI) allows you to take control of your own digital identity. Personal and company information are often spread across different platforms and at risk of data breaches. SSI provides a secure and decentralized solution. With SSI, individuals and companies can manage and verify their own identity information, without relying on centralized authorities or intermediaries. + +- Concept of Decentralized Identity + The idea is that a cryptic identifier is resolved to a document including two major things. + The public key of the entity while the corresponding private key is in possession of the entity itself + A list of links to specific service endpoints. One of these endpoints is the credential endpoint which offers *Verifiable Credentials* describing attributes of the entity +- Verifiable Credentials (VCs) + Verifiable credentials are a digital representation of attributes about the entity that can be easily shared and verified by multiple entities. These credentials are typically issued by trusted organizations or institutions. + These credentials are structured in a standardized format using open standards like W3C's Verifiable Credentials Data Model (https://www.w3.org/TR/vc-data-model/). VCs consist of verifiable claims that contain specific information about an entity and are digitally signed by the issuer using cryptographic techniques. This cryptographic signature ensures the integrity and authenticity of the credential and can be verified by relying parties. + +In Catena-X Self-Sovereign Identity (SSI) is used to manage the identity of the Dataspace Participants on company level (company identity) and offering the ability to exchange participant attributes and information in a secure and standardized way. The individual level on users are not in scope - user identities are managed via the known OIDC flow. +Additionally eventhrough SSI enables you to fully self-manage your identity, it still allows to use provider offers - it is not necessarily limited to own managed solutions only. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +#### AUDIENCE + +The description flows and data models for participants attributes -if form of Verifiable Credentials- is based on the definitions documented in the IATP which can be found here: +[Identity-Trust](#31-normative-references) + +The standard is relevant for the following roles, as they must be certified against it: + +- Core Service Provider (A/B) (in case issuer components or wallets are provided) +- Enablement Service Provider (only in case wallets are provided) + +The standard is relevant for the following role, as they must certify against this standard: + +- Conformity Assessment Body + +The standard is relevant for the following role, as they carry out their advisory on the basis of this standard. + +- Advisory Provider + +#### SCOPE + +The self-sovereign identity (SSI) standard within the catena-X framework encompasses various aspects related to wallet creation, credential schemas, revocation flow, presentation flow, and lifecycle management. This standard document outlines the specifications and guidelines for implementing SSI within the catena-X ecosystem. It describes: + +- **Wallet Creation**: The creation of a wallet for the participant which is used by him/her to exchange identity information in the process of data exchange +- **Credential Schemas** participant attributes credential schema specification of credentials that participants can utilize within the catena-X ecosystem. It provides the credential schema that capture relevant identity attributes and enable seamless interoperability between different solutions. Note: additional schemas and credentials may be covered in additional standard documents +- The lifecycle of the participant's Verifiable Credentials from issuance to revocation including the following: + - Issuance of Verifiable Credentials + - Presentation of Verifiable Credentials in form of a Verifiable Presentation + - Revocation of issued Verifiable Credentials + +### 1.2 CONTEXT AND ARCHITECTURE FIT + +> *This section is non-normative* + +Identity and Access Management (IAM) is a mandatory basic infrastructure for every IT-System. The identity +of any entity and actor (company, user, or technical client/connector) is the summary of the describing +attributes (e.g., Company Name, Address, Tax Number, etc.). To cover all aspects of interoperability, sovereignity, scalability, multi-network-connection, etc. the concept of authentication and authoriztaion needs with special focus on data transfer a robust, possible self-managed identity solution. The company must be identifiable in an independent way and interoperable in all networks. With SSI and Credentials this can get archived on a company level. + +The purpose of this document is to unify the Digital Company Identity in a self-sovereign +manner. The digital identity of a Catena-X partner is the basis of any interaction with other partners. To +ensure independence and data sovereignty of one identity provider this identity - as the summary of the +describing attributes - must be under the sovereignty of the respective partner company. + +### 1.3 ARCHITECTURE OVERVIEW + +> *This section is non-normative* + +Not applicable. + +### 1.4 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes +in this specification are non-normative. Everything else in this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, **REQUIRED**, **SHOULD** +and **SHOULD NOT** in this document document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] +when, and only when, they appear in all capitals, as shown here. + +### 1.5 PROOF OF CONFORMITY + +> *This section is non-normative* + +`Core Service Provider (A/B)` + +A Core Service Provider **MUST** ensure that all dataspace participants have an identity wallet implementing the IATP protocol. +A Core Service Provider can provide such a Wallet Hosting Service itself or consume a third-party Wallet Service. +In both cases the Core Service Provider **MUST** ensure that the offered Wallet Service provides the following requirements + +- follow the W3C Standard for Self Sovereign Identity ([Decentralized + Identifiers (DIDs) v1.0 (w3.org)](https://www.w3.org/TR/did-core/)) + +- Implements an appropriate Access Management to the Wallet using the Secure Token Service Concept described here [identity.protocol.base.md#6-using-the-oauth-2-client-credential-grant-to-obtain-access-tokens-from-an-sts](https://github.com/eclipse-tractusx/identity-trust/blob/2ef77ee4c08713e557581ab507acc618c738d170/specifications/identity.protocol.base.md#6-using-the-oauth-2-client-credential-grant-to-obtain-access-tokens-from-an-sts) + +- furthermore implement at least the following functionalities + - Issuance of Verifiable Credentials + - Verification of Verifiable Credentials + - Presentation of Verifiable Credentials + +To validate these criteria for an own implementation of the Core Service Provider the following information **MUST** be handed to the Conformity Assessment Body by the Core Service Provider: + +- A documentation (e.g. based on Arc42) explaining the architecture, process flows and data structures of the implementation. + +`Enablement Service Provider` + +An Enablement Service Provider (i.e. Wallet Service Provider) **MUST** ensure that the provided Wallet Service provides the following requirements: + +- follow the W3C Standard for Self Sovereign Identity ([Decentralized Identifiers (DIDs) v1.0 (w3.org)](https://www.w3.org/TR/did-core/)) + +- Implements an appropriate Access Management to the Wallet using the Secure Token Service Concept described here [identity.protocol.base.md#6-using-the-oauth-2-client-credential-grant-to-obtain-access-tokens-from-an-sts](https://github.com/eclipse-tractusx/identity-trust/blob/2ef77ee4c08713e557581ab507acc618c738d170/specifications/identity.protocol.base.md#6-using-the-oauth-2-client-credential-grant-to-obtain-access-tokens-from-an-sts) + +- furthermore implement at least the following functionalities + + - Issuance of Verifiable Credentials + - Verification of Verifiable Credentials + - Presentation of Verifiable Credentials + +To validate these criteria for an own implementation of the Core Service Provider please collect the following documents: + +- Arch42 Documentation explaining the architecture, access management + and process flows of the implementation + +```text +Disclaimer: + +In future releases it will be possible for every participant to operate the identity wallet either by itself or by an other 3rd party provider (Wallet Hosting Provider) +An appropriate migration process from the offered Wallet Service to a self-hosted or 3rd party Wallet will be described; till that - the SSI service is a single solution service only +``` + +### 1.6 TERMINOLOGY + +> *This section is non-normative* + +| Term | Abbrevation | Description | Reference | +| ----------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| Self-Sovereign Identity | SSI | Self-sovereign identity is the concept of individuals and organisations having full control and ownership over their digital identity, enabling them to manage and share their personal information securely and selectively. | | +| Decentralized Identifiers | DID | Decentralized identity refers to a system where individuals and organisations have control over their identity and personal data through the use of blockchain or other decentralized technologies, eliminating the need for a third-party identity provider | [W3C vc-data-model](https://www.w3.org/TR/vc-data-model/) | +| Verifiable Credential | VC | A Verifiable credentials is a digital representations of information about an individual or organisation that can be easily shared and independently verified by multiple entities based on cryptographic concepts. VCs follow well defined Data Models to enable reusability and interoperability. | [W3C did-core](https://www.w3.org/TR/did-core) | +| Verifiable Presentation | VP | A Verifiable presentation is the data model and the process of securely sharing and presenting digitally verifiable credentials or attributes to a relying party or verifier for authentication and validation purposes. The concept of VPs ensures both the authenticity of the holder and that of the VC | [W3C did-core](https://www.w3.org/TR/did-core/) | +| Identity and Trust Protocoll | IATP | IATP contains normative documents defining protocols and flows within the Identity and Trust system to be used in Tractus-X projects such as Catena-X | [Tractus-X IATP](https://github.com/eclipse-tractusx/identity-trust/tree/main) | +| Connector | | (Catena-X) Technical component that allows business applications to interact with each other within a dataspace. Also referenced as Dataspace Client | | +| Dataspace Client | | (Catena-X) Technical component that allows business applications to interact with each other within a dataspace. Also referenced as Connector | | +| Business Partner Number (BPN) | | Every participant in the Catena-X network has a unique, unchangeable identifier, called business partner number (BPN). The legal entity of an organization is represented by the Business Partner Number Legal Entity (BPNL) | [CX - 0010 Business Partner Number](https://catena-x.net/de/standard-library)| +|Secure Token Service |STS|The Secure Token Service is a logical endpoint that creates self-issued identity tokens on behalf of a participant: |[Tractus-X STS](https://github.com/eclipse-tractusx/identity-trust/blob/2ef77ee4c08713e557581ab507acc618c738d170/specifications/identity.protocol.base.md#6-using-the-oauth-2-client-credential-grant-to-obtain-access-tokens-from-an-sts)| + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2. TRUSTFUL IDENTIFICATION OF PARTICIPANT AGENTS IN THE NETWORK + +> *This section is normantive* + +This section describes the following functionalities and processes: + +- Creation of a participant wallet +- Credential Issuance +- Credential Presentation +- Credential Verification +- Credential Revocation + +### 2.1 CREATION OF A PARTICIPANT WALLET + +> *This section is normantive* + +The purpose of this section is to ensure consistency and compatibility between the Core Service Provider, the Issuer and and a Wallet Provider. By following these guidelines, we can streamline the integration process and improve the overall user experience. To ensure this, this section describes the guidelines for the integration interfaces of the "Create Wallet Customer Instance" functionality. All Provider of a Wallet that want to integrate as wallet provider to the CSP-A/CSP-B MUST adhere to these guidelines. Additionally the MUST criteria for Core Service Providers are referenced as well. + +### 2.1.1 INTERFACE DETAILS + +The "Create Wallet Customer Instance" interface MUST meet the following requirements: + +**Data Format**: The data exchanged between the CSP system and the external registration component SHOULD BE in JSON format. This ensures a standardized and easily parsable data structure. + +**Endpoint**: All endpoints in the reference of this standard section MUST be secured and accessible via HTTPS. This ensures data confidentiality and integrity during transmission. + +**Authentication**: All endpoints in the reference of this standard section MUST support authentication mechanism OAuth 2.0 OIDC via technical user (ClientID and Secret). This ensures secure access to the wallet functionality and prevents unauthorized usage. + +**Interface Implementation**: + +**Outbound Interface** +The Core service provider MUST support the "Create Wallet Customer Instance" interface via the integration to the Enablement Service Provider (Wallet) and triggering of the wallet instance creation as part of the registration process with the following details: + +```json +{ + "businessPartnerNumber": "string", + "companyName": "string", + "didUrl": "string" +} +``` + +The endpoint itself is provided by the Enablement Service Provider and described below. + +**Inbound "Create Customer Instance" - Request Body Structure**: The request structure (of the external wallet provided inbound interface) MUST follow the request body structure: + +**Method:** `POST` + +```json +{ + "businessPartnerNumber": "string", + "companyName": "string", + "didUrl": "string" +} +``` + +Additional fields may be included based on specific business requirements. + +**Outbound "Create Customer Instance Asynchron Response" - Request Body Structure**: The REST API request body implemented by the Core Service Provider MUST follow to: + +**Method:** `POST` + +```json +{ + "didDocument": "string", + "authenticationDetails": [ + { + "authenticationServiceUrl": "string", + "clientID": "uuid", + "clientSecret": "****" + } + ] +} +``` + +- did document (to be stored inside the portal db, connected to the company; and to be published by the operator/portal) +- authenticationServiceUrl (to be stored since we need this later for being able to push VCs into the walletTenant) +- clientId (to be stored since we need this later for being able to push VCs into the walletTenant) +- clientSecret (to be stored since we need this later for being able to push VCs into the walletTenant) +- tbc: walletCustomerInstanceUrl (under clarification; might be not relevant) + +The Enablement Service Provider MUST support the "Asynchrone Response of Create Wallet Customer Instance" interface with the integration to the Core Service Provider provided endpoint. + +**Error Handling**: The wallet provider inbound interface should handle errors gracefully and support following scenarios: + +- 400 endpoint not found +- 401 no valid user credentials +- 403 missig permission +- 404 unallowed didURL, unallowedCompanyName, unallowed BPN + +**NOTE**: The interface definition above is valid for Catena-X release 24.05, it is planned to further enhance and adjust the *“way of integration”* for a multi-wallet concept with the upcoming releases. + +### 2.2 CREDENTIAL ISSUANCE + +The Self-Sovereign Identity (SSI) credential issuance flow enables the issuance and verification of verifiable credentials. Verifiable credentials are digital representations of identity information that can be securely shared and verified without relying on a central authority. + +The SSI credential issuance flow involves a series of steps to ensure the authenticity, integrity, and privacy of the issued credentials. These steps typically include: + +**Identity Verification**: Before issuing a credential, the identity of the participant requesting the credential needs to be verified. This involves a thorough verification process to ensure that the participant's identity information is accurate and reliable. + +**Credential Request**: Once the participant's identity is verified, they can request a specific credential from the issuer. The credential request includes the necessary information and attributes required for the issuance of the credential. + +**Credential Issuance**: The issuer, after validating the participant's request and verifying the necessary information, generates and issues the verifiable credential. The credential is digitally signed by the issuer to ensure its authenticity and integrity. + +**Credential Delivery**: The issued credential is securely delivered to the participant's wallet or digital identity repository. The delivery mechanism ensures the confidentiality and privacy of the credential during transit. + +The SSI credential issuance flow is designed to provide participants with secure and trusted credentials that can be easily shared and verified across different systems and organizations. It empowers individuals with control over their identity information while maintaining the privacy and integrity of their credentials. + +### 2.2.1 CREDENTIAL BASICS + +- The encoding format for VCs and Verifiable Presentations (VP) is JWT `ES256K/secp256k1`. +- Authorities allowed to issue credentials are public available (via BPN, name and credentialType) via the Association or CSP-B +- All Authroities **MUST** follow the allowed credential type schema as defined in this standard as well as the CX-0050 + +The CSP-B **MUST** ensure that participants of the dataspace holding the folloiwng credentials as a minimum: + +- Membership Credential +- Business Partner Number (BPN) Credential + +Any other credentials which may defined in this or other Catena-X standards are optional for the dataspace entry. + +Following the credential and the according schemas for the mentioned credential are described: + +### 2.2.1.1 MEMBERSHIP CREDENTIAL + +The membership credential confirms that the participant is onboarded to Catena-X and agreed to the Catena-X terms and conditions. The credential is issued to the participant by the core service provider or a core service provider assigned issuer. The data model of the membership credential must contain the attributes depicted in the following schema: + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "MembershipCredential"], + "issuanceDate": "{creation date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "{did holder}", + "holderIdentifier": "{bpn}", + "memberOf": "{membership level}" + } +} +``` + +The content of the credential is explained as follows: + +- `id` is the uuid of the newly created credential - the uuid is defined by the issuer component +- `context` is fix defined for the current used schema - we should already consider that the schema might get updated in future ideally we are flexible to have this scenario that the old schema is set to "INACTIVE" and a new schema is used for new created credentials +- `type` is fix defined for this specific credential +- `issuanceDate` calculated on runtime +- `expirationDate` calculated by the issuer component based on defined credential static data expiry date => always not > 12 month +- `issuer` holds the issuer did +- `credentialSubject` + contains attributes of the participant, the credential is issued for + - `id`: the did of the participant + - `type`: the type of attribute, in this case the `MembershipCredential` + - `holderdentifier`: the BPN of the participant + - `memberOf`: the network for which the membership credential is issued + +### 2.2.1.2 BUSINESS PARTNER NUMBER + +This section is not aimed to standardize the content, structure, and the creation of the Business Partner Number. This is done by the standard CX-0010. This section describes the schema of the Business Partner Number credential issued for the participant. + +The BPN credential contains the Business Partner Number of the part and is issued by the core service provider. The data model of the BPN credential **MUST** contain the attributes depicted in the following schema: + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "BpnCredential"], + "issuanceDate": "{creation date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "{did holder}", + "holderIdentifier": "{bpn}", + "bpn": "{bpn}" + } +} +``` + +The content of the credential is explained as follows: + +- `id` is the uuid of the newly created credential - the uuid is defined by the issuer component +- `context` is fix defined for the current used schema - we should already consider that the schema might get updated in future ideally we are flexible to have this scenario that the old schema is set to "INACTIVE" and a new schema is used for new created credentials +- `type` is fix defined for this specific credential +- `issuanceDate` calculated on runtime +- `expirationDate` calculated by the issuer component based on defined credential static data expiry date => always not > 12 month +- `issuer` holds the issuer did +- `credentialSubject` + contains attributes of the participant, the credential is issued for + - `id`: the did of the participant + - `holderIdentifier`: the Business Partner Number (BPN) of the holder + - `bpn`: the actual Business Partner Number (BPN) + +### 2.2.1.3 SPECIAL CREDENTIAL: DISMANTLER CREDENTIAL + +Unlike the Business Partner Number and the Membership Credential, the Dismantler Credential is optional for specific participants being a dismantler. This credential is use case specific and issued to the participant by the Core Service Provider after the according verification of the participant. +It can be used to manage access to data based on the fact, that the consumer is a dismantler. +The schema of the Catena-X Dismantler Credential is depicted as follows: + +```json +{ + "id": "uuid", + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" + ], + "type": ["VerifiableCredential", "DismantlerCredential"], + "issuanceDate": "{creation date - format: 2022-06-16T18:56:59Z}", + "expirationDate": "{expiration date - format: 2022-06-16T18:56:59Z}", + "issuer": "{did issuer}", + "credentialSubject": { + "id": "did:web:com.example.participant", + "holderIdentifier": "BPNL000000001", + "activityType": "vehicleDismantle", + "allowedVehicleBrands": ["Alfa Romeo", "Alpina", "BMW"] + } +} +``` + +The content of the credential is explained as follows: + +- `id` is the uuid of the newly created credential - the uuid is defined by the issuer component +- `context` is fix defined for the current used schema - we should already consider that the schema might get updated in future ideally we are flexible to have this scenario that the old schema is set to "INACTIVE" and a new schema is used for new created credentials +- `type` is fix defined for this specific credential +- `issuanceDate` calculated on runtime +- `expirationDate` calculated by the issuer component based on defined credential static data expiry date => always not > 12 month +- `issuer` holds the issuer did +- `credentialSubject` + contains attributes of the participant, the credential is issued for + - `id`: the did of the participant + - `holderdentifier`: the BPN of the participant + - `acticityType`: the type of services offered by the participant. + *For Release 24.05 the allowed entry is `vehicleDismantle`* + - `allowedVehicleBrands`: the brands of vehicles the participant is allowed and/or certified to offer the services listed in `activityTypes`. + *For Release 24.05 this is a free text field and **MAY** contain any string.* + +### 2.3 CREDENTIAL PRESENTATION + +- IATP - Auth Flow + > *This section is normantive* + +The presentation of verifiable credentials between the connectors (described in CX-0018) of the participants follows the Identity And Trust Protocol [Identity-Trust](#31-normative-references), which describes the details of the credential presentation in the document [Credential Presentation Protocol](#31-normative-references). + +The following figure shows the presentation flow defined by IATP + +![auth.flow.png](./assets/auth.flow.png) + +Explanation of the entities: + +- `Client`: the `connector` (described in CX-0018) of the data consumer that will request data from a data provider +- `Secure Token Service`: is a logical endpoint that creates self-issued identity tokens on behalf of a participant". This concept is described here: [identity.protocol.base.md#6-using-the-oauth-2-client-credential-grant-to-obtain-access-tokens-from-an-sts](https://github.com/eclipse-tractusx/identity-trust/blob/2ef77ee4c08713e557581ab507acc618c738d170/specifications/identity.protocol.base.md#6-using-the-oauth-2-client-credential-grant-to-obtain-access-tokens-from-an-sts) +- `Credential Service`. the service of the participant's wallet or the wallet tenant which provides the verifiable credentials wrapped into a verifiable presentation +- `Verifier`: the `connector` (described in CX-0018) of the data provider that will be requested for data provision and will receive the credentials in a verifiable presentation by presenting the previously received token + +### 2.4 CREDENTIAL REVOCATION + +> *This section is normative* + +The issuer **MUST** ensure the support of the following 3 credential revocation/expiry scenarios: + +- Revocation by holder +- Revocation by issuer +- Expiry + +In all the three scenarios the credential **MUST** be set invalid to enable validation services such as the connector to identify the invalid/inactive credential and to decline the credential usage for any data access/view/negotation process. + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +- [CX-0010:2.0 Business Partner Number](https://catena-x.net/de/standard-library) +- [CX-0011:1.0 Issuing Agency](https://catena-x.net/de/standard-library) +- [CX-0015:1.0 IAM & Access Control Paradigm](https://catena-x.net/de/standard-library) +- [CX-0050:2.0 Framework Agreement Credential](https://catena-x.net/de/standard-library) + +- [Identity Trust](https://github.com/eclipse-tractusx/identity-trust/tree/0.8.1/specifications) +- [Credential Presentation Protocol](https://github.com/eclipse-tractusx/identity-trust/blob/0.8.1/specifications/verifiable.presentation.protocol.md) + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +Not applicable. + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +Not applicable. + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +Not applicable. + +### TABLES + +> *This section is non-normative* + +Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/docs/standards/CX-0149-Dataspaceidentityandidentification/assets/auth.flow.png b/docs/standards/CX-0149-Dataspaceidentityandidentification/assets/auth.flow.png new file mode 100644 index 000000000..5026ecdcb Binary files /dev/null and b/docs/standards/CX-0149-Dataspaceidentityandidentification/assets/auth.flow.png differ diff --git a/docs/standards/changelog.md b/docs/standards/changelog.md new file mode 100644 index 000000000..b046c9484 --- /dev/null +++ b/docs/standards/changelog.md @@ -0,0 +1,168 @@ +--- +position: 1 +sidebar_class_name: separator-top +--- + +# Changelog + +## Summary of Release Jupiter + +- 13 new standards +- 34 updated standards +- 60 deprecated standards + +### A) List of new and updated standards + +> Note: Be aware that more information regarding the changes can be found within the standard documents within the section "***COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD***" + +#### Sovereign Data Exchange & Semantics + +| CX-Nr. | Standard Name | Version | Management Summary | +|-----------|-----------|:-----------:|--------------------| +| CX-0002 | Digital Twins in Catena-X | 2.2 |
    • Remove all normative references to the EDC implementation.
    • Declare outdated typization mechanism (asset:prop:type) optional
    | +| CX-0018 | Dataspace Connectivity | 3.0 |
    • Adopt pinned versions of IATP, DSP, policy definitions.
    • Specify HTTPS and AmazonS3 transfer processes
    | +| CX-0067 | Ontology Models in Catena-X | 1.1 |
    • New subchapters Digital Twin and Ontologies, Taxonomy, Asset Content Description, Modeling of the Functions have been added.
    • Text, images and code snippets have been modified to make them easier to understand.
    | +| CX-0084 | Federated Queries In Data Spaces | 1.2 |
    • External links have been changed to improve readability.
    • The examples have been updated to reflect recent developments.
    • The the Asset Content Description subsection has been added.
    • Code snippets and text updates in Agent-Related EDC Assets
    | +| CX-0126 | Industry Core: Part Type |  2.0 |
    • Added new content in Section 2.1.3
      • New paragraph "Conventions for Use Case Policy in context data exchange"
      • Notes for versioning
    • Changes in specific AssetIds of Digital Twins in **Section 2.1.4**:
      • removed assetLifeCyclePhase
      • digitalTwinType is now mandatory (before it was optional)
    • Replaced standardized aspect model in **Section 3.1**:
      • removed PartAsPlanned 2.0.0
      • replaced with newly standardized PartTypeInformation 1.0.0 (see link to changelog in section of the aspect model)
    • New version of aspect model in **Section 3.2**:
      • SingleLevelBomAsPlanned 3.0.0 (see link to changelog in section of the aspect model)
    • Newly standardized aspect model in **Section 3.3**:
      • SingleLevelUsageAsPlanned 2.0.0 (see link to changelog in section of the aspect model)
    • Added Unique ID Push Notification API in **Section 4.1** as content of the industry core
    • deleted "Every certified business application relying on aspects models of this standard **MUST** be able to consume data conformant to the semantic models specified in this document." from **Section 3**
    | +| CX-0127 | Industry Core: Part Instance | 2.0 |
    • New versions of aspect models in **Section 3**
      • SerialPart 3.0.0 (see link to changelog in section of the aspect model)
      • Batch 3.0.0 (see link to changelog in section of the aspect model)
      • JustInSequencePart 3.0.0 (see link to changelog in section of the aspect model)
      • SingleLevelBomAsBuilt 3.0.0 (see link to changelog in section of the aspect model)
    • Newly standardized aspect models in **Section 3**
      • SingleLevelUsageAsBuilt 3.0.0 (see link to changelog in section of the aspect model)
    • Aspect model JustInSequencePart now **MUST** be provided when creating a digital twin for a Just-In-Seuqence-Part (was optional before) in **Section 2.1.2**
    • Changes in specificAssetIds of Digital Twins in **Section 2.1.4**
      • Removed assetLifeCyclePhase
      • DigitalTwinType is now mandatory (before it was optional)
      • Added intrinsicId specifically for Digital Twins for serialized parts, batches and just-in-sequence-parts
      • Removed partInstanceId from Digital Twins for batches and just-in-sequence-parts
    • Added Unique ID Push Notification API in **Section 4.1** as content of industry core
    • New paragraph "Conventions for Use Case Policy in context data exchange" in **Section 2.1.3**
    • Added notes for versioning in **Section 2.1.3**
    • Deleted "Every certified business application relying on aspects models of this standard **MUST** be able to consume data conformant to the semantic models specified in this document." from **Section 3**
    | + +#### Business Partner Data Management + +| CX-Nr. | Standard Name | Version | Management Summary | +|-----------|-----------|:-----------:|--------------------| +| CX-0012 | Business Partner Data Pool API | 4.0 |
    • changed and added the detailed asset structure
    • removed classification sub-object
    • added "is Catena-X Member data" attribute
    • removed "api/catena/" from the endpoint definitions
    • added data sovereignty chapters as additional requirements
    • fix changelog controller endpoint for business-partners to match the reference implementation
    | +| CX-0074 | Business Partner Gate API | 3.0 |
    • Changed and added the detailed asset structure
    • removed classification sub-object
    • removed business partner state and introduced separate states at representation classes
    • removed "api/catena/" from the endpoint definitions
    • added data sovereignty chapters as additional requirements
    | +| CX-0076 | Golden Record End to End Requirements Standard | 1.2 |
    • Adjustment of Table 2 in chapter 2.1.9 Golden Record Output Requirements].
    • Adding Tax Jurisdiction Code
    • Adjustment in chapter 2.1.11 Confidence Level
    • Adjust text for validation interval
    • District and Region is now mandatory for Romania as listed in Table 2
    | +| CX-0077 | Data Quality Dashboard | 1.2 |
    • Corrected 2.3.3 - country list
    • Added chapter 3.5 Data Types and 3.6 Data Attributes
    • Added chapter 3.7 for data sovereignty as additional requirement
    | +| CX-0078 | Bank Data Verification Dashboard | 1.2 |
    • Corrected 2.3. - country list
    • Added chapter 3.4 Data Types and 3.5 Data Attributes
    • Added chapter 3.6 for data sovereignty as additional requirement
    • Corrected 2.3. - Enhanced usage policies of BDV API
    | +| CX-0079 | Natural Person Screening Dashboard | 1.2 |
    • Natural Person Screening Dashboard v1.2
    • Corrected 2.3 - country list
    • Added chapter 3.6 Data Types and 3.7 Data Attributes
    • Added chapter 3.8 for data sovereignty as additional requirement
    | +| CX-0080 | BPDM Fraud Prevention Service | 1.1 |
    • Added chapter 2.6 Data Types and 2.8 Data Attributes.
    • Added chapter 2.7 for data sovereignty as additional requirement.
    | +| CX-0081 | BPDM Country Risk | 2.2 |
    • Update on data asset and added new context for Country Risk
    • Added new section for Additional Requirements
    • Affected chapters are 2.2.3 Data Asset Structure & 2.2.5 Additional Requirements
    | +| CX-0116 | Sanction Watchlist Dashboard | 1.2 |
    • Corrected 2.3 - country list
    • Added chapter 3.4 Data Types and 3.5 Data Attributes
    • Added chapter 3.6 for data sovereignty as additional requirement
    | +| CX-0135 | Company Certificate Management | 2.0 |
    • Added a new attribute 'status' to the data model (1.5.11 Status)
    • Added new certificate types (1.5.2 TYPE)
    | + +#### Identity Management + +| CX-Nr. | Standard Name | Version | Management Summary | +|-----------|-----------|:-----------:|--------------------| +| CX-0013 | Identity of Member Companies | 2.0 | Deprecation of the Summary Credential. | +| CX-0049 | DID Document Schema | 2.0 | Re-definition of the structure of the did-document. | +| CX-0050 | Framework Agreement Credential | 2.0 | Re-definition of the Framework Agreement structure. | +| CX-0149 | Verified Company Identity | 1.0 |
    • This document combines the previous standards `CX - 0016 Company Attribute Verification v.1.1.0` and `CX - 0017 Company Role by the Connector v.1.0.1` including all needed information for the identification of a participant and the Dataspace clients acting on behalf of them
    • Introducing the *Identity and Trust Protocol (IATP)* used within the identity presentation flow
    • Introducing an API specification for the *Creation of Participants Wallet* as a foundation for the usage of multiple Wallet providers.
    | + +#### Onboarding + +| CX-Nr. | Standard Name | Version | Management Summary | +|-----------|-----------|:-----------:|--------------------| +| CX-0006 | Registration and Initial Onboarding | 2.0 | Updated following chapters:
    • 2.3.4 Company Data Validation
    • 2.3.8 Gaia-X
    And added:
    • 2.3.5 Business Partner Number Creation
    • 2.3.6 Wallet Tenant Creation
    • Credential Storage
    • Registration Approval and Dataspace Access
    | +| CX-0009 | CX Registration API | 2.0 | Update of the endpoint details which MUST/SHOULD get followed by the Core Service Provider and/or Onboarding service provider. Endpoint path as well as request/response body. | + +#### Data Chain Management + +| CX-Nr. | Standard Name | Version | Management Summary | +|-----------|-----------|:-----------:|--------------------| +| CX-0005 | Item Relationship Service API | 2.1 |
    • Adoption of the industry core standards (CX-0126 and CX-0127)
    • Update of optional endpoints
    | +| CX-0045 | Aspect Model Data Chain Template | 1.3 |
    • Adoption of the industry core standards (CX-0126 and CX-0127)
    • Update of the template from BAMM to SAMM
    | +| CX-0139 | Information as a Service – External Data Provider | 1.0  | The Scope of this Standard is to enable Third-Party Information Provider to deliver Data from outside Catena-X inside Catena-X. This Standard is generic to every Use Case and qualifies Information aaS Provider as a potential Data Provider for a Use Case defined Business Application. The Data can be delivered only to a specific Use Case within Catena-X, realised in an certified Business Application. By this way the Standard enables Third-Party Information Provider to deliver Data from outside Catena-X inside Catena-X and at the same time limits Data Delivery to existing Use Cases, avoiding Violations or Bypasses of existing Standards and Regulations within Catena-X. | + +#### Resiliency + +| CX-Nr. | Standard Name | Version | Management Summary | +|-----------|-----------|:-----------:|--------------------| +| CX-0115 | Manufacturing Capability Exchange | 1.0 | Manufacturing-as-a-Service (MaaS) scenarios focus on connecting buyers looking for manufacturers in possession of the available production know-how and resources to produce specific products. The standard makes use of the newly introduced all-in-one use-case template. The Manufacturing Capability data model is being expanded to include the entities Machine, Tool, and Material, along with their corresponding properties. Additionally, an API is defined, so that these Manufacturing Capabilities can be exchanged in a standardized way.
    *Note*: The CX-0115 standard obsoletes CX-0052 Manufacturing Capability Aspect Mode l v1.0.0 | +| CX-0118 | Delivery Information Exchange | 2.0 | Changes:
    • integration and usage of digital twins as defined in **CX-0002** Digital Twins in Catena-X
    • harmonization of aspect model in accordance with **CX-0126** Industry Core: Part Type
    • discontinuation of the proprietary API used in v1.0.0 of this standard
    • grammatical, spelling and semantic improvements
    New Content:
    • added a note on the obligation of standard implementers to make aware that sensitive data is being handled, see Chapter 2.1.3.
    | +| CX-0120 | Short-Term Material Demand Exchange | 2.0 | Changes:
    • integration and usage of digital twins as defined in **CX-0002** Digital Twins in Catena-X
    • harmonization of aspect model in accordance with **CX-0126** Industry Core: Part Type
    • new specific submodel `io.catenax.short_term_material_demand:1.0.0:ShortTermMaterialDemand` from `io.catenax.material_demand:1.0.0:MaterialDemand`
    • discontinuation of the proprietary API used in v1.0.0 of this standard
    • grammatical, spelling and semantic improvements
    New Content:
    • added a note on the obligation of standard implementers to make aware that sensitive data is being handled, see **Chapter 2.1.3**
    | +| CX-0121 | Planned Production Output Exchange | 2.0 | Changes:
    • integration and usage of digital twins as defined in **CX-0002** Digital Twins in Catena-X
    • harmonization of aspect model in accordance with **CX-0126** Industry Core: Part Type
    • discontinuation of the proprietary API used in v1.0.0 of this standard
    • grammatical, spelling and semantic improvements
    New Content:
    • added a note on the obligation of standard implementers to make aware that sensitive data is being handled, see **Chapter 2.1.3**
    | +| CX-0122 | Item Stock Exchange | 2.0 | Changes:
    • integration and usage of digital twins as defined in **CX-0002** Digital Twins in Catena-X
    • harmonization of aspect model in accordance with **CX-0126** Industry Core: Part Type
    • discontinuation of the proprietary API used in v1.0.0 of this standard
    • grammatical, spelling and semantic improvements
    New Content:
    • added a note on the obligation of standard implementers to make aware that sensitive data is being handled, see **Chapter 2.1.3**
    | +| CX-0128 | Demand and Capacity Management Data Exchange | 2.0 |
    • Replaced `MaterialDemand` with `WeekBasedMaterialDemand` aspect model
    • Added deactivation of `WeekBasedCapacityGroup` to *Section 4.2.2.2*
    • Added deactivation of `WeekBasedMaterialDemand` to **Section 4.1.2.2**
    • Added **Chapter 2.3** Additional Requirements
    • Added **Chapter 5.10** Supply Chain Disruption Notifications
    • Added **Chapter 5.11** Demand Volatility Metrics
    • Added Agreed Capacity to **Section 5.6.1**
    • Added Repositories to **Annexes**
    • Updated References in **Chapter 7**
    • Updated `WeekBasedCapacityGroup` aspect model
    • Updated `WeekBasedMaterialDemand` aspect model
    • Updated `MessageHeaderAspect` version in **Chapter 4**
    • Updated Policies in **Chapter 6**
    • Updated choice of words and writing pattern throughout this standard
    | +| CX-0129 | Request-for-Quotation Exchange | 2.0 | In this version of the standard, the processes entity of the RequestForQuotation semantic model has been replaced by the "Bill of Process" data model (cf. **Chapter 3.2**) | +| CX-0133 | Online Control and Simulation | 2.1 |
    • Updated references to new versions
    • Providers must ensure BPNL provisioning to OSim
    | +| CX-0142 | Shop-Floor-Information-Service | 1.0 | The current version of the standard provides two different kinds of data: Production Forecasting, and Production Tracking data. To give an example of forecasting data, suppose a customer wants to know when production is expected to start. He can use the Shop-Floor-Information-Service in order to get the information either directly, via cyclic messages or via notifications when the calculated production dates change. As an example of production tracking, a customer can request certain production attributes collected during production, such as the torque of a particular process step. This data can then be used for both documentation and tracking.
    *Note*: This standard
    • Merges CX-0068, CX-0069 and CX0075 by combining the different standards that describe the data model, the API and and the process into this combined standard.
    • Additional functionality added: production tracking aspects.
    • Update of Production Forecast Models due to update of CX-header.
    | +| CX-0145 | Days of supply Exchange | 1.0 | Days of Supply (DoS) in logistics is a critical metric used to estimate how long current inventory levels will last under normal consumption patterns. This calculation is essential in supply chain management as it assists in forecasting when stock replenishment is needed, thereby preventing stock shortages or overstocking. It plays a significant role in ensuring efficient inventory turnover, maintaining a balance between having enough stock to meet demand and avoiding excess inventory that ties up capital. To effectively address the challenges associated with manual calculation and estimation of Days of Supply, the standardization and interoperable exchange of this data among Catena-X business partners is essential. Establishing a standardized semantic definition to describe Days of Supply and a common API is a fundamental step to enable this exchange and foster compatibility. This approach maximizes the range of solutions available to mitigate potential supply shortages and supports precise inventory planning. | +| CX-0146 | Supply Chain Disruption Notifications | 1.0 | The Catena-X Supply Chain Disruption Notifications Standard is created for all members of the automotive supply chain. The aim is to have a functionality to easily and quickly inform the affected supply chain partners in case of supply chain disruptions at some point in the value chain. Having this information is key to be able to take the right countermeasures and make the whole value chain more resilient. Recent incidents (e.g. semi-conductor-crisis or COVID pandemic) have demonstrated the requirement for such a fast standardized process among all partners. | + +#### PLM and Quality + +| CX-Nr. | Standard Name | Version | Management Summary | +|-----------|-----------|:-----------:|--------------------| +| CX-0059 | Behavioral Twin Endurance Estimator Use Case | 2.0 | This standard upgrades the triangle (previously CX-0059:1.2) to an Use Case Standard and consolidates the contents of the previously independent standards CX-0056, CX-0057 and CX-0058 within a single comprehensive standard. | +| CX-0105 | Asset Tracking Use Case | 1.1 | This standard upgrades the triangle (previously CX-0105:1.0) to an Use Case Standard and consolidates the contents of the previously independent standards CX-0070, CX-0083, CX-0004 and CX-0106 within a single comprehensive standard. Note: No content relevant to the certification has been changed. | +| CX-0123 | Quality Use Case Standard | 2.0 |
    • Update semantic models `QualityTask`, `PartsAnalyses`, `ManufacturedPartsQualityInformation`, `Fleet.DiagnosticData`, `Fleet.ClaimData`
    • Update model Fleet.Vehicles and integrate model `Vehicle.ProductDescription`
    • New semantic models Early Warning Norification and Failure Pattern
    • Update 2.1 Data Sharing Rules
    • Define Notification Process and API
    | +| CX-0125 | Traceability Use Case | 2.0 |
    • Redundancies to the standard CX-0127 in all relevant chapters removed: Submodel `SerialPart`, Submodel `Batch`, Submodel `SingleLevelBoMAsBuilt`
    • Adapted parts (introductions, examples) of the standard document contents to suit the use case specifications
    • Quality Alerts are set to mandatory
    • New paragraph "Conventions for Use Case Policy in context data exchange" in **Section 2.1.3**
    • Added notes for versioning in **Section 2.1.3**
    • Deleted "Every certified business application relying on aspects models of this standard **MUST** be able to consume data conformant to the semantic models specified in this document." from **Section 3**
    • Deleted old references in **Section 6.1**
    | +| CX-0138 | Use Case Behaviour Twin Endurance Estimator | 1.0 | The 1.0 version changed from a triangle (originally CX-0089) to an Use Case Standard and consolidates the contents of the previously independent standards CX-0057, CX-0088, CX-0090 within a single comprehensive standard. | +| CX-0141 | Health Indicator Use Case | 1.0 | This standard focuses on the Health Indicator Use Case. The Health Indicator recieves dynamic input data, that has been recorded in the vehicle, through the Catena-X network. The input data, combined with additional product knowledge by the service provider, is used to calculate precise health indicator values for specific components | + +#### Sustainability + +| CX-Nr. | Standard Name | Version | Management Summary | +|-----------|-----------|:-----------:|--------------------| +| CX-0117 | Use Case Circular Economy - Secondary Marketplace | 1.0 | CX-0117 Use Case Circular Economy - Secondary Marketplace v1.0.0 is a new standard which is based on the deprecated CX-0100 Triangle for Secondary Marketplace v.1.0.0 standard. The data models from:
    • CX-0033 Data Model ReturnRequest (deprecated)
    • CX-0034 Data Model Battery Pass (deprecated)
    • CX-0035 Data Model Marketplaceoffer (deprecated)have been included with their newest released versions to assure consistency between standards.
    | +| CX-0131 | Circularity Core | 1.1 | Adoption of the industry core standards (CX-0126 and CX-0127)
    Additionally, CX-0131 merges (and, thus, obsoletes) the following aspect models:
    • CX-0036: Aspect Model: QualityTask
    • CX-0037: Aspect Model: Vehicle.ProductionData
    • CX-0038: Aspect Model: Fleet.DiagnosticData
    • CX-0039: Aspect Model: Fleet.ClaimData
    • CX-0040: Aspect Model: PartAnalyses
    • CX-0041: Aspect Model: ManufacturedPartsQualityInformation
    • CX-0091: Aspect Model: Fleet.Vehicles
    • CX-0092: Aspect Model: QualityTaskAttachment
    • CX-0107: Aspect Model: Reuse Certificate 
    • CX-0109: Aspect Model: Refrubishing Certificate
    • CX-0111: Aspect Model: Remanufacturing Certificate
    • CX-0147: Aspect Modelt Non-ReusableParts
    • CX-0148: Aspect Model Repair Certificate
    | +| CX-0136 | Use Case PCF | 1.0 | This standard focuses on the PCF (Product Carbon Footprint) exchange use case. This includes relevant requirements for:
    • data provider, that want to provide PCF data through Catena-X,
    • data consumer, that are want to consume PCF values in Catena-X and
    • application developer/ provider supporting the provisioning and consuming of PCF values.
    It will provide information about the used core components as well as the structure of the Digital Twin Registry entry, the data model exchanged and the EDC (Eclipse Dataspace Connector) data structure. | +| CX-0143 | Use Case Circular Economy - Digital Product Passport Standard | 1.0 | This standard focuses on the digital product passport use case. This includes relevant requirements for
    • data provider, that want to provide different passports through Catena-X,
    • data consumer, that are searching for different passports in Catena-X, and
    • application developer / provider supporting the provisioning and consuming of passport data.
    Specific passports that shall be mentioned here are the battery passport and the transmission passport, which are first realizations of product passports in Catena-X. | +| CX-0144 | ESS Use Case Standard | 1.0 | Catena-X aims to support supply chain due diligence obligations in a market environment that miss full up- and downstream transparency. This is argued to be relevant for Environmental and Social Standards (ESS) incident tracking, without compromising GAIA-X and Catena-X principles like data sovereignty, interoperability, standardization, and use of federated services.
    In case a violation against these laws occurs, an ESS incident can be created and transmitted to the Catena-X network. The Catena-X network and the ESS use case standard support the Catena-X members in this process.
    *Note:* The ESS incident aspect model, which was described in CX-0113, has been integrated into this document. | + +### B) List of deprecated standards + +| CX-Nr. | Standard Name | Reason to depricate | +|:--------------------|:-----------------------------------------------|:--------------------------------------------------------------------------------------------------| +| CX-0019 | SerialPart | Merged by CX-0127 Industry Core Part Instance | +| CX-0020 | Batch | Merged by CX-0127 Industry Core Part Instance | +| CX-0021 | SingleLevelBoMAsBuilt | Merged by CX-0127 Industry Core Part Instance | +| CX-0042 | Aspect Model - SinglelevelBomAsPlanned | Merged by CX-0126 Industry Core Part Type | +| CX-0043 | Aspect Model - PartAsPlanned | Merged by CX-0126 Industry Core Part Type | +| CX-0022 | Notification API | Merged by CX-0125 Traceability Use Case | +| CX-0023 | Notification Process | Merged by CX-0125 Traceability Use Case | +| CX-0060 | Tracebility BomAsBuild Triangle | Merged by CX-0125 Traceability Use Case | +| CX-0036 | Aspect Model: QualityTask | Merged by CX-0131 Circularity Core | +| CX-0037 | Aspect Model: Vehicle.ProductionData | Merged by CX-0131 Circularity Core | +| CX-0038 | Aspect Model: Fleet.DiagnosticData | Merged by CX-0131 Circularity Core | +| CX-0039 | Aspect Model: Fleet.ClaimData | Merged by CX-0131 Circularity Core | +| CX-0040 | Aspect Model: PartAnalyses | Merged by CX-0131 Circularity Core | +| CX-0041 | Aspect Model: ManufacturedPartsQualityInformation | Merged by CX-0131 Circularity Core | +| CX-0091 | Aspect Model: Fleet.Vehicles | Merged by CX-0131 Circularity Core | +| CX-0092 | Aspect Model: QualityTaskAttachment | Merged by CX-0131 Circularity Core | +| CX-0098 | Aspect Model: Secondary Material Content | Merged by CX-0131 Circularity Core | +| CX-0099 | Data Model: Certificate of Decommissioning | Merged by CX-0131 Circularity Core | +| CX-0107 | Aspect Model: Reuse Certificate  | Merged by CX-0131 Circularity Core | +| CX-0108 | Aspect Model: Waste Certificate | Merged by CX-0131 Circularity Core | +| CX-0109 | Aspect Model: Refrubishing Certificate | Merged by CX-0131 Circularity Core | +| CX-0111 | Aspect Model: Remanufacturing Certificate | Merged by CX-0131 Circularity Core | +| CX-0112 | Aspect Model: Material Recycling Certificate | Merged by CX-0131 Circularity Core | +| CX-0033 | Data Model ReturnRequest | Merged into CX-0117 Use Case Circular Economy - Secondary Marketplace | +| CX-0035 | Data Model Marketplaceoffer | Merged into CX-0117 Use Case Circular Economy - Secondary Marketplace | +| CX-0057 | Aspect Model for user estimated loading | Merged into CX-0059 and CX-0138 Use Case Behaviour Twin Endurance Estimator | +| CX-0056 | Semantic Model: Classified Load Spectrum | Merged into CX-0059 Use Case Behaviour Twin Endurance Predictor | +| CX-0058 | API: Endurance Predictor | Merged into CX-0059 Use Case Behaviour Twin Endurance Predictor | +| CX-0088 | Aspect Model for Remaining Useful Life data | Merged into CX-0138 Use Case Behaviour Twin Endurance Estimator Digital Product Pass | +| CX-0090 | API Endurance Estimator | Merged into CX-0138 Use Case Behaviour Twin Endurance Estimator | +| CX-0089 | Triangle Behavioral Twin Endurance Estimator Service | Merged into CX-0138 Use Case Behaviour Twin Endurance Estimator Digital Product Pass | +| CX-0026 | PCF Data Model | Merged into CX-0143 Use Case PCF | +| CX-0028 | PCF Request API | Merged into CX-0143 Use Case PCF | +| CX-0134 | PCF Calculation Integration | Merged into CX-0143 Use Case PCF | +| CX-0063 | PCF Triangle | Merged into CX-0143 Use Case PCF | +| CX-0052 | Manufacturing Capability Aspect Model | Merged into CX-0115 Manufacturing Capability Exchange | +| CX-0100 | Triangle for Secondary Marketplace | Merged into CX-0117 Use Case Circular Economy - Secondary Marketplace | +| CX-0016 | Company Attribute Verification | Merged into CX-0149 Verified Company Identity | +| CX-0017 | Company Role by the Connector | Merged into CX-0149 Verified Company Identity | +| CX-0051 | Summary Credentials | Deprecated with the introduction of IATP (see CX-0018 and CX-0149) | +| CX-0061 | Triangle Traceability Data Provisioning Digital Twin As Planned | Merged into CX-0125 Traceability Use Case | +| CX-0062 | Traceability Notifications Triangle | Merged into CX-0125 Verified Company Identity | +| CX-0093 | Aspect Model Traction Battery Code | Merged into CX-0125 Verified Company Identity | +| CX-0070 | Asset Tracking Platform API Standardization | Merged into CX-105 Asset Tracking Use Case Identity | +| CX-0083 | Aspect Model IotSensorDeviceDefinition | Merged into CX-105 Asset Tracking Use Case Identity | +| CX-0104 | Aspect Model AssetTrackerLinks v1.0.0 | Merged into CX-105 Asset Tracking Use Case Identity | +| CX-0106 | Aspect Model IotSensorData | Merged into CX-105 Asset Tracking Use Case Identity | +| CX-0096 | Triangle For Digital Product Pass | Merged into CX-0143 Use Case Circular Economy - Digital Product Passport Standard | +| CX-0034 | Data Model Battery Pass | Merged into CX-0143 Use Case Circular Economy - Digital Product Passport Standard | +| CX-0095 | Data Model: Transmission Pass | Merged into CX-0143 Use Case Circular Economy - Digital Product Passport Standard | +| CX-0103 | Aspect Model Digital Product Passport | Merged into CX-0143 Use Case Circular Economy - Digital Product Passport Standard | +| CX-0068 | MP Shop Floor Information Service API | Merged into CX-0142 Shop Floor Information Service | +| CX-0069 | Shop-Floor-Information-Service Aspect Model | Merged into CX-0142 Shop Floor Information Service | +| CX-0075 | Shop-Floor-Information-Service Process | Merged into CX-0142 Shop Floor Information Service | +| CX-0113 | Aspect Model ESS Incident Data Model | Merged into CX-0144 Shop Floor Information Service | +| CX-0072 | OSim Process & Core Business Logic | Merged into CX-0133 Online Control and Simulation | +| CX-0073 | OSim API | Merged into CX-0133 Online Control and Simulation | +| CX-0087 | OSim Data Model: Materialflow Simulation Result | Merged into CX-0133 Online Control and Simulation | +| CX-0085 | Product Stock Aspect Model | Merged into CX-0133 Online Control and Simulation | +| CX-0086 | Product Stock Exchange API | Merged into CX-0133 Online Control and Simulation | diff --git a/docs/standards/overview.md b/docs/standards/overview.md index d55528995..9f855458e 100644 --- a/docs/standards/overview.md +++ b/docs/standards/overview.md @@ -1,6 +1,7 @@ --- sidebar_position: 1 title: Overview Standards +sidebar_class_name: separator-bottom --- :::danger diff --git a/docs/working-model/00-legal/00-legal.md b/docs/working-model/00-legal/00-legal.md new file mode 100644 index 000000000..a7b30c87f --- /dev/null +++ b/docs/working-model/00-legal/00-legal.md @@ -0,0 +1,3 @@ +# Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](https://catenax-ev.github.io/copyright). diff --git a/docs/working-model/00-legal/_category_.json b/docs/working-model/00-legal/_category_.json index 7f9786c51..3e51f9250 100644 --- a/docs/working-model/00-legal/_category_.json +++ b/docs/working-model/00-legal/_category_.json @@ -1,6 +1,6 @@ { "label": "Legal", - "position": 5, + "position": 7, "collapsible": true, "collapsed": true } diff --git a/docs/working-model/02-organizational-structure/02-03-tooling.md b/docs/working-model/02-organizational-structure/02-03-tooling.md index d9c0f9cc1..955180b40 100644 --- a/docs/working-model/02-organizational-structure/02-03-tooling.md +++ b/docs/working-model/02-organizational-structure/02-03-tooling.md @@ -3,19 +3,19 @@ sidebar_position: 3 title: Tooling --- -This is just a short description about the different tools. The usage of these tools is described in the coresponding [sections](../03-process-from-idea-to-production/03-01-process-from-idea-to-production.md). +This is just a short description about the different tools. The usage of these tools is described in the corresponding [sections](../03-process-from-idea-to-production/03-01-process-from-idea-to-production.md). ## Microsoft Teams Microsoft Teams is a good starting point for Expert Groups and Committees. After they are built up, they can decide to use GitHub in a private repository, or MS Team in a private channel. :::warning -All open-source content has to be in Tractus-X. The privtae teams and repository are more for the day to day work, files and task planner/ issue tracker +All open-source content has to be in Tractus-X. The private teams and repository are more for the day to day work, files and task planner/ issue tracker ::: ### Main topic -- Communication sytsem +- Communication system - Taskplanning - Filestorage - "Knowledgestore" @@ -33,7 +33,7 @@ There are two main organizations in GitHub: - for the open-source part (reference implementations and Kits) GitHub is mandatory. Its used for planning, issue tracking, discussions, development, reviews and release etc. - for the standardization part, GitHub is also set as mandatory -- for Committee work and Expert Groups the Association provides private repositories within the catenax-eV organization +- for Committee work and Expert Groups the Association provides private repositories within the *catenax-eV* GitHub organization ::: @@ -43,11 +43,11 @@ In Eclipse Tractus-X we mainly use open-source tooling provided by the Eclipse F The Eclipse Foundation provides a `Matrix Chat` for open communication. It can be used via Eclipse account. There are several rooms available for different topics. The main room for Tractus-X is [#tractusx:matrix.eclipse.org](https://matrix.to/#/#tractusx:matrix.eclipse.org). -There is also a [tractusx-dev mailing list](https://accounts.eclipse.org/mailing-list/tractusx-dev) available to reach out to all subscribed Tractus-X contributer. Within this list the importent open meetings are shared as also committer elections and other importnet information related to Tractus-X. +There is also a [tractusx-dev mailing list](https://accounts.eclipse.org/mailing-list/tractusx-dev) available to reach out to all subscribed Tractus-X contributor. Within this list the important open meetings are shared as also committer elections and other important information related to Tractus-X. :::info -Please subscribe to the mailinglist. +Please subscribe to the mailing list. ::: @@ -55,6 +55,6 @@ Please subscribe to the mailinglist. :::info -TBD +Work in progress ::: diff --git a/docs/working-model/02-organizational-structure/02-organizational-structure.md b/docs/working-model/02-organizational-structure/02-organizational-structure.md index 11e89a660..e68dd6924 100644 --- a/docs/working-model/02-organizational-structure/02-organizational-structure.md +++ b/docs/working-model/02-organizational-structure/02-organizational-structure.md @@ -13,8 +13,7 @@ sidebar_position: 1 ### Catena-X Automotive Network e.V :::info -ToDo: Michael -Update Grafik nach dem 01.04. mit Update von Jan +Work in progress ::: - Catena-X is structured along Committees and Expert Groups @@ -42,7 +41,7 @@ The sharepoint pages can only be accessed by association members. ### Eclipse Tractus-X Project :::info -ToDo: Michael +Work in progress ::: - Tractus-X is structured along products (repos) or use cases @@ -50,13 +49,13 @@ ToDo: Michael - Each contributor can propose features in sig-release - Committers make the decision which features will be committed in the next release - Outcome: - - Planning: Committed, periodized backlog for a release + - Planning: Committed, prioritized backlog for a release - Release: Release Train ### Other Initiatives :::info -ToDo: Michael +Work in progress ::: - Other initiatives (such as M-X) can use our processes to propose... diff --git a/docs/working-model/03-process-from-idea-to-production/03-01-process-from-idea-to-production.md b/docs/working-model/03-process-from-idea-to-production/03-01-process-from-idea-to-production.md index cbf887601..cb2460215 100644 --- a/docs/working-model/03-process-from-idea-to-production/03-01-process-from-idea-to-production.md +++ b/docs/working-model/03-process-from-idea-to-production/03-01-process-from-idea-to-production.md @@ -22,7 +22,7 @@ We use the Committees and Expert Groups of the Catena-X e.V. to align, develop a ### Refine feature - Responsible: Feature Author -- Description: After creating the feature proposal the feature author has to continously refine the feature until it contains the minimal feature content, so that it can be valited. This step might be obsolete if all information are added when creating the feature proposal. +- Description: After creating the feature proposal the feature author has to continuously refine the feature until it contains the minimal feature content, so that it can be validated. This step might be obsolete if all information are added when creating the feature proposal. - Possible outcomes: Submit for validation ### Validate minimal feature content @@ -39,14 +39,14 @@ We use the Committees and Expert Groups of the Catena-X e.V. to align, develop a - Description: Once the feature proposal contains at least the minimal feature content, its strategic fit is going to be evaluated by the topic owner - Possible outcomes: - Feature proposal fit strategy: If the feature proposal strategically fits it is going to be added to the Inbox. - - Strategic fit cant be assest: If the strategic fit cant be assest by the topic owner the feature proposal is being send back to the feature author with the request to further refine the feature proposal. + - Strategic fit can't be assessed: If the strategic fit can't be assessed by the topic owner the feature proposal is being send back to the feature author with the request to further refine the feature proposal. - Feature proposal does NOT fit: If the topic owner assess the feature proposal as not fitting the strategy, the feature proposal is going to be rejected. In this case the feature proposal is not going to be implemented. ### Refine feature to meet DoE - Responsible: Feature author - Description: Once the feature is validated, the feature author has to further refine the feature to meet the DoE. The refinement can be done by setting up individual refinement meetings for the feature proposal and inviting relevant people or by presenting the feature proposal in the Open Refinement. Each feature proposal has to be presented at least once in the Open Refinement so that the whole community has the chance to provide feedback. -- Possbile outcomes: DoE complete +- Possible outcomes: DoE complete ### Present feature proposal in Open Refinement @@ -72,7 +72,7 @@ We use the Committees and Expert Groups of the Catena-X e.V. to align, develop a - Responsible: Committers - Description: The committers are deciding on the scope of the upcoming release. All feature proposals presented in the Open Planning are going to be prioritized. - Possible outcomes: - - Committed: The feature proposal gets the committment from the committers and is added to the upcoming release. + - Committed: The feature proposal gets the commitment from the committers and is added to the upcoming release. - Not committed: The feature proposal is not committed by the committers and wont be part of the upcoming release. The feature proposal is going to be presented again in the Open Planning for the following release. ## Artifacts @@ -91,7 +91,7 @@ The minimal feature content is a subset of the DoE. It defines the minimal infor |Information|Description| |-----------|-----------| -|Feature author|Responsbile person to carry the feature proposal through the validation and refinement process| +|Feature author|Responsible person to carry the feature proposal through the validation and refinement process| |Description|Description of WHAT the feature proposal is about.| |Business value|Description of WHY the feature proposal is relevant.| |Acceptance criteria|Conditions that must be satisfied for the feature proposal to be accepted| @@ -102,8 +102,8 @@ The minimal feature content is a subset of the DoE. It defines the minimal infor |-----------|-----------| |Minimal feature content|*see Minimal feature content*| |Dependencies|Dependencies with other products or issues are identified and categorized via GitHub labels| -|Risks|Known rsiks are properly adressed| -|Enablers|Required enablers are defined (*isnt that a dependency?*)| +|Risks|Known risks are properly addressed| +|Enablers|Required enablers are defined (*isn't that a dependency?*)| |High level architecture (building block view)|| |Key dates and milestones|Key dates and milestones are defined using GitHub milestone declaration| |Testing|Test scenarios, test cases and test data are available| @@ -113,22 +113,22 @@ The minimal feature content is a subset of the DoE. It defines the minimal infor ### Open Refinement -The Open refinement is ment to... +The Open refinement is meant to... -The Catena-X association communicates and coordiantes the open refinement and open planning meetings via the a Tractus-X [News Page](https://eclipse-tractusx.github.io/blog) and the Tractus-X [Mailing List](https://accounts.eclipse.org/mailing-list/tractusx-dev). Feature authors must make sure to subscribe! The meetings are also be published (with meeting session and calender.ics) on the open meetings page. +The Catena-X association communicates and coordinates the open refinement and open planning meetings via the a Tractus-X [News Page](https://eclipse-tractusx.github.io/blog) and the Tractus-X [Mailing List](https://accounts.eclipse.org/mailing-list/tractusx-dev). Feature authors must make sure to subscribe! The meetings are also be published (with meeting session and calender.ics) on the open meetings page. ### Open Planning -During the Open Planning the items for upcoming release are planned. All feature proposals that were handed in on time are going to be presented to the audience. The Open Planning is the last chance to provide feedback about the scope of the feature proposal. After the presentation of the feature proposal by the feature author, the committers are going to prioritize the feature proposal in alignment with the topic owner. A feature proposal becomes part of the upcoming release only by receiving the commitment by the committes and not by being presented in the Open Planning! +During the Open Planning the items for upcoming release are planned. All feature proposals that were handed in on time are going to be presented to the audience. The Open Planning is the last chance to provide feedback about the scope of the feature proposal. After the presentation of the feature proposal by the feature author, the committers are going to prioritize the feature proposal in alignment with the topic owner. A feature proposal becomes part of the upcoming release only by receiving the commitment by the committees and not by being presented in the Open Planning! -To enter the Open Plannung a feature proposal must meet the DoE X days before the Open Planning (Cut-Off)! Feature proposal that meet the DoE after the Cut-Off won't be considered in the Open Planning. This means it will likely be deferred to a future release. +To enter the Open Planning a feature proposal must meet the DoE X days before the Open Planning (Cut-Off)! Feature proposal that meet the DoE after the Cut-Off won't be considered in the Open Planning. This means it will likely be deferred to a future release. | Tasks | Documents (e.g. Standards) | Reference Impl. | Outcome | |-------------------|----------------------------|-----------------|---------| | Feature Proposal | Refinement Meetings | In sig release | Proposals by C-X e.V. Overview of all feature proposals incl. acceptance criteria. (Task break down over all affected teams / dependencies.) DOE ??? | | Feature Commitment | Planning Meetings | In sig release | Decision by committer group Committed, prioritized backlog for the next release. Coordination / refinement / prioritization of new ideas, business requirements, features (scope C-X only) | -| | C-X association tooling | Sig-release | Priotized list of Catena-X business requirements (proposal) | -| | C-X association tooling | Sig-release: Discussions, Issues | Product Priotized list of overall business requirements | +| | C-X association tooling | Sig-release | Prioritized list of Catena-X business requirements (proposal) | +| | C-X association tooling | Sig-release: Discussions, Issues | Product prioritized list of overall business requirements | | | Association meetings (e.g., roadmap) | Tractus-X open meetings (e.g., refinement, planning, …) | Roadmap and issues updated (?) | | Development of Deliverable | Create (normative) documents | Create open source software / KITs | Deliverables created (Normative Documents, KITs, Reference Implementation (complies to C-X Standards)) | | Review of Deliverables | Content reviews in Expert Group | Code reviews (PRs) in Tractus-X | Deliverables reviewed | @@ -151,7 +151,7 @@ Responsible: Committee & Expert Group Once a new feature proposal has been made for the Tractus-X project, it enters a validation phase where the Committees assigns it to the relevant Expert Group. -- **Validation:** The Committee assignes the feature to the matching Expert Group (at least two specific contacts). The Expert Group will review the proposal to ensure it aligns with the project's goals and standards. +- **Validation:** The Committee assigns the feature to the matching Expert Group (at least two specific contacts). The Expert Group will review the proposal to ensure it aligns with the project's goals and standards. - **Request for Additional Details:** If the proposal lacks necessary details, the reviewing bodies may ask the author for additional information or clarification. ### Feature refinement @@ -160,25 +160,25 @@ Responsible: Feature author After being validated and initially prioritized by the Expert Group, the refinement process starts. The feature author must gather their peer group (such as experts, contributors, and committers) for example by publishing a virtual meeting invite for the feature issue to be refined. -The goal is to have features that fullfill the following **Definition of Entry (DoE)**: +The goal is to have features that fulfill the following **Definition of Entry (DoE)**: - Feature author defined: The designated point of contact for any questions related to the feature during the refinement, planning and development phase (e.g., subject matter expert). Not necessarily responsible for the technical implementation of a feature. -- Feature desciption is available -- Required enablers are defined and aligned (e.g., architecutre, infrastructure, compliance) +- Feature description is available +- Required enablers are defined and aligned (e.g., architecture, infrastructure, compliance) - High-level architecture (building-block-view) - Key dates and milestones are defined using GitHub milestone declaration - Business value is defined - Test scenarios, test cases and test data are available -- Accpetance criteria are defined +- Acceptance criteria are defined - Feature estimation available (based on story points) - Developer team for feature implementation defined - Dependencies with other products or issues are identified and categorized via GitHub labels -- Known rsiks are properly adressed +- Known risks are properly addressed - No open questions left - First implementation issues are defined in the corresponding repository and linked to the feature (optional) ... -Ultimately, the decision regarding maturity is made jointly by the affected products and contributers in the open refinement meetings. +Ultimately, the decision regarding maturity is made jointly by the affected products and contributors in the open refinement meetings. **Feature author responsibility in the refinement:** @@ -207,13 +207,13 @@ By following this process, authors can ensure their feature proposals are consid ## Open Release Planning Meeting -Once a feature is through the propose and refinement process (2.) the feature will be presented in the open planning meeting and the committer will prioritize them based on the strategic / technical fit and ressource commitment in alignment with the Expert Groups of the Catena-X association. +Once a feature is through the propose and refinement process (2.) the feature will be presented in the open planning meeting and the committer will prioritize them based on the strategic / technical fit and resource commitment in alignment with the Expert Groups of the Catena-X association. The open release planning meeting also called Program Increment (PI) planning is a critical event in the Tractus-X project where contributors, committers, Expert Groups, and Committees come together to define the scope for the next release. This process ensures that the project's roadmap is aligned with stakeholder expectations and the project's strategic objectives. Here's how the release Planning process typically unfolds: - **Attendees:** Contributors, committers, Expert Groups, and Committees attend the release planning meeting. - **Scope Definition:** The main objective of this meeting is to determine the scope of the upcoming release. This involves discussing the refined features and confirming the prioritized backlog. -- **Priorize backlog:** The backlog will be reviewed to ensure that it aligns with the project's strategic direction and available resources. Before the open release planning meeting, Committees and Expert Groups can pre-prioritize the backlog. However, the final prioritization is done by the committers. +- **Prioritized backlog:** The backlog will be reviewed to ensure that it aligns with the project's strategic direction and available resources. Before the open release planning meeting, Committees and Expert Groups can pre-prioritize the backlog. However, the final prioritization is done by the committers. ### Decision-Making by Committers @@ -223,10 +223,10 @@ The open release planning meeting also called Program Increment (PI) planning is ### Outcome of Open Planning -- **Priortized backlog:** Decision by committer group Committed, prioritized backlog for the next release. +- **Prioritized backlog:** Decision by committer group Committed, prioritized backlog for the next release. - **Resource commitment:** Teams and individuals commit to the work they will deliver, fostering accountability and setting clear expectations for the upcoming release. -- **Updated roadmap:** The project's roadmap is updated to reflect the decisions made during the release planning, providing transparency to stakeholders and the community. [TO-DO clarifiy location of the roadmap / where will this be published] -- **Decisions are documented:** All decisions and commitments made during the planning are documented in the decision board or directly in the comment section of a feature. [TO-DO link to the architecture decsion board] +- **Updated roadmap:** The project's roadmap is updated to reflect the decisions made during the release planning, providing transparency to stakeholders and the community. [TO-DO clarify location of the roadmap / where will this be published] +- **Decisions are documented:** All decisions and commitments made during the planning are documented in the decision board or directly in the comment section of a feature. [TO-DO link to the architecture decision board] - **Communication plan:** After the planning a communication via mailing-list will be done by the project lead including the relevant links and decisions. ## Feature Development @@ -254,8 +254,9 @@ Contributors can create pull requests (PRs) for their developed features at any A PR must include the feature code, adapted helm chart(s), technical documentation as well as product tests (e.g., unit tests) and product integration tests (e.g., by using helm charts or mocks). All these tests must be passed locally before the PR can be submitted. **Hint:** You can find the latest versions of the product helm charts in our release changelog. + :::info -ToDo: Insert Link! Previous link was broken. +Work in progress ::: At least two committer must review the PR, including the source code, test results and the compliance with the Tractus-X release guidelines (TRGs), and approve the merging of these changes. In case there are change requests or defects that a committer cannot solve, the contributor must address these changes before merging. @@ -295,8 +296,8 @@ Defects or unexpected behavior must be reported as bugs in the [sig-release repo There are various testing artifacts, that are either managed in Tractus-X GitHub or the Test Management Tool. -- In **GitHub** we manage the different user journys and related business scenarios as .md files. -- In the **Test Management Tool** we manage test cases, test sets (opt.), test exectuions as well as test plans and reports. +- In **GitHub** we manage the different user journeys and related business scenarios as .md files. +- In the **Test Management Tool** we manage test cases, test sets (opt.), test executions as well as test plans and reports. | Artifact | Artifact Owner | \# per Release | | ----------------- | ----------------------- | -------------- | @@ -348,10 +349,10 @@ Catena-X **Release Management** is a crucial component within the broader Catena In essence, Catena-X Release Management acts as a central hub that coordinates the complex interplay between Catena-X and Tractus-X releases, ensuring smooth integration, high-quality deliverables, and customer satisfaction. -## Security Mangement +## Security Management :::info -ToDo: Security, Managing and Reporting Vulnerabilities, Communication +Work in progress ::: ## Relevant Links @@ -361,13 +362,13 @@ ToDo: Security, Managing and Reporting Vulnerabilities, Communication ## FAQs **How are the open meetings communicated?** -The Catena-X association will communicate and coordiante the open refinement and open planning meetings vi the a Tractus-X [News Page](https://eclipse-tractusx.github.io/blog) and the Tractus-X [Mailing List](https://accounts.eclipse.org/mailing-list/tractusx-dev). Please make sure that you subscribe. The meetings will also be published (with meeting session and calender.ics) on the open meetings page. +The Catena-X association will communicate and coordinate the open refinement and open planning meetings vi the a Tractus-X [News Page](https://eclipse-tractusx.github.io/blog) and the Tractus-X [Mailing List](https://accounts.eclipse.org/mailing-list/tractusx-dev). Please make sure that you subscribe. The meetings will also be published (with meeting session and calender.ics) on the open meetings page. **Who can propose a feature?** Anyone can **propose a feature**, including Committees, Expert Groups, and other initiatives. However, we require a dedicated feature author for further refinement and the breakdown into implementation issues. **How to handle dependencies?** -Dependencies can be discussed in our open refinement meetings as well as via our other communication channels (e.g. martix chat or bilateral sessions). Please refer to our Tractus-X [communication rules](https://eclipse-tractusx.github.io/community/intro). +Dependencies can be discussed in our open refinement meetings as well as via our other communication channels (e.g. matrix chat or bilateral sessions). Please refer to our Tractus-X [communication rules](https://eclipse-tractusx.github.io/community/intro). **Who gives access to the sig-release repository to enable planning process?** Please refer to our Tractus-X [Getting Started Guide](https://eclipse-tractusx.github.io/docs/oss/getting-started). diff --git a/docs/working-model/03-process-from-idea-to-production/03-04-Issue-Process.md b/docs/working-model/03-process-from-idea-to-production/03-04-Issue-Process.md index 43f2b02c4..5c96a74d5 100644 --- a/docs/working-model/03-process-from-idea-to-production/03-04-Issue-Process.md +++ b/docs/working-model/03-process-from-idea-to-production/03-04-Issue-Process.md @@ -9,7 +9,7 @@ Table of Contents 2. [Release Planning](#2-release-planning) :::info -[General Feature Contributions](#general-feature-contributions) is this still needed? +Work in progress ::: ## General Feature Contributions @@ -53,7 +53,7 @@ Once a new feature proposal has been made for the Tractus-X project, it enters a - **Responding to Feedback:** The contributor is responsible for addressing any feedback provided by the Expert Group or committee. This may include providing additional details or making revisions to the proposal. - **Sub Task Creation:** If required, the contributor may need to create sub-tasks that break down the feature into manageable pieces. This helps in tracking progress and facilitates easier review. -- **Timely Updates:** The contributor must update the feature details within the given timeframe. Prompt responses and updates are crucial to keep the proposal moving forward. +- **Timely Updates:** The contributor must update the feature details within the given time frame. Prompt responses and updates are crucial to keep the proposal moving forward. ### 1.3 Feature Validation and Approval diff --git a/docs/working-model/CHANGELOG.md b/docs/working-model/CHANGELOG.md index 91b46ecef..98ee652c9 100644 --- a/docs/working-model/CHANGELOG.md +++ b/docs/working-model/CHANGELOG.md @@ -1,8 +1,12 @@ +--- +sidebar_position: 6 +--- + # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). -## [1.0.0] - 2024-06-24 +## [0.1.0] - 2024-06-24 ### Added diff --git a/docs/working-model/overview.md b/docs/working-model/overview.md index 0bd580c2f..1a4a0e95c 100644 --- a/docs/working-model/overview.md +++ b/docs/working-model/overview.md @@ -25,6 +25,6 @@ title: Overview ## Non-Normative -:::info +:::warning[NOTE] This is not a normative Document! ::: diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 6ebe881a6..9da7cc6a1 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -41,7 +41,7 @@ const config: Config = { sidebarPath: './sidebars.ts', versions: { current: { - label: 'Next', + label: 'Jupiter (preview)', }, }, }, @@ -111,8 +111,8 @@ const config: Config = { label: 'Release Management', }, { - to: '/CHANGELOG', - label: 'Changelog', + to: '/release-notes', + label: 'Release notes', }, ], }, diff --git a/src/css/custom.css b/src/css/custom.css index 95a9187dc..24417e35d 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -71,3 +71,11 @@ padding: 8px; border-radius: 8px; } + +.separator-top{ + border-top: 1px solid #CCC; +} + +.separator-bottom{ + border-bottom: 1px solid #CCC; +} \ No newline at end of file diff --git a/src/pages/CHANGELOG.md b/src/pages/CHANGELOG.md deleted file mode 100644 index eac027547..000000000 --- a/src/pages/CHANGELOG.md +++ /dev/null @@ -1,11 +0,0 @@ -# Changelog - -## [24.03] - 2024-03-08 - -### Added - -### Updated - -### Unchanged - -### Known knowns diff --git a/src/pages/release-notes.md b/src/pages/release-notes.md new file mode 100644 index 000000000..3a65d2f02 --- /dev/null +++ b/src/pages/release-notes.md @@ -0,0 +1,36 @@ +# Release Notes + +## [JUPITER (PREVIEW)] + +### Catena-X Standards + +- 12 new standards, completing the set of Catena-X' initial use cases +- 33 updated standards to ensure quality, coherence and the implementation of our "breaking change" via SSI +- 31 deprecated standards in the course of consolidation to achieve more user-friendliness +- updated modular certification framework + +details to be found [here](https://catenax-ev.github.io/docs/next/standards/changelog) + +### Catena-X Operating Model + +- updated to version 3.0 enabling many new ecosystem components such as the OSP role, Catena-X Sandboxes and an overhaul to release management focused on stability and reliability + +details to be found [here](https://catenax-ev.github.io/docs/next/operating-model/changelog) + +### Catena-X Regulatory Framework + +- introduced the official Catena-X ODRL profile including standardized Catena-X policies. +- adding various pre-defined use case frameworks, e.g. Circular Economy, Demand and Capacity Management, etc. + +details to be found [here](https://catenax-ev.github.io/docs/next/regulatory-framework/change-log) + +### Tractus-X Features & KITs + +A comprehensive, coherent and compatible set of development artefacts. Highlights include: + +- an update to the Multi-OpCo solutions +- the full implementation of the Industry Core KIT +- the advancement of Self Sovereign Identity concepts +- several improvements to the user-friendliness of KITs based on feedback received to date, making Tractus-X overall more accessible and welcoming to newcomers and veterans alike. + +details to be found [here](https://eclipse-tractusx.github.io/CHANGELOG) diff --git a/versioned_docs/version-24.03/standards/CX-0001-EDCDiscoveryAPI/CX-0001-EDCDiscoveryAPI.md b/versioned_docs/version-24.03/standards/CX-0001-EDCDiscoveryAPI/CX-0001-EDCDiscoveryAPI.md index 3c7e5bc96..379d22587 100644 --- a/versioned_docs/version-24.03/standards/CX-0001-EDCDiscoveryAPI/CX-0001-EDCDiscoveryAPI.md +++ b/versioned_docs/version-24.03/standards/CX-0001-EDCDiscoveryAPI/CX-0001-EDCDiscoveryAPI.md @@ -1,4 +1,4 @@ -# CX-0001 EDC Discovery API v.1.0.2 +# CX-0001 EDC Discovery API v1.0.2 ## ABSTRACT @@ -448,3 +448,7 @@ HTTP standard response codes that MUST be used. - GAIA-X Trustframework: [https://gaia-x.eu/wp-content/uploads/2022/05/Gaia-X-Trust-Framework-22.04.pdf](https://gaia-x.eu/wp-content/uploads/2022/05/Gaia-X-Trust-Framework-22.04.pdf) - CX - 0006 Registration and initial onboarding - CX - 0010 Business Partner Number + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0002-DigitalTwinsInCatenaX/CX-0002-DigitalTwinsinCatenaX.md b/versioned_docs/version-24.03/standards/CX-0002-DigitalTwinsInCatenaX/CX-0002-DigitalTwinsinCatenaX.md index bc365eb4a..b98eef3e5 100644 --- a/versioned_docs/version-24.03/standards/CX-0002-DigitalTwinsInCatenaX/CX-0002-DigitalTwinsinCatenaX.md +++ b/versioned_docs/version-24.03/standards/CX-0002-DigitalTwinsInCatenaX/CX-0002-DigitalTwinsinCatenaX.md @@ -1,4 +1,4 @@ -# CX-0002 Digital Twins in Catena-X v.2.1.0 +# CX-0002 Digital Twins in Catena-X v2.1.0 ## ABSTRACT diff --git a/versioned_docs/version-24.03/standards/CX-0003-SAMMSemanticAspectMetaModel/CX-0003-SAMMSemanticAspectMetaModel.md b/versioned_docs/version-24.03/standards/CX-0003-SAMMSemanticAspectMetaModel/CX-0003-SAMMSemanticAspectMetaModel.md index a3eb4e573..63bf7d82b 100644 --- a/versioned_docs/version-24.03/standards/CX-0003-SAMMSemanticAspectMetaModel/CX-0003-SAMMSemanticAspectMetaModel.md +++ b/versioned_docs/version-24.03/standards/CX-0003-SAMMSemanticAspectMetaModel/CX-0003-SAMMSemanticAspectMetaModel.md @@ -1,4 +1,4 @@ -# CX-0003 SAMM Aspect Meta Model v.1.1.0 +# CX-0003 SAMM Aspect Meta Model v1.1.0 ## ABSTRACT @@ -355,3 +355,7 @@ urn:samm:io.catenax.material_for_recycling:1.0.0#MaterialForRecycling - [Semantic Data Structuring](https://raw.githubusercontent.com/OpenManufacturingPlatform/openmanufacturingplatform.github.io/master/docs/sds/OMP-Semantic-Data-Structuring-Whitepaper.pdf). Whitepaper. 2021-08-16. Open Manufacturing Platform. - [Product Modeling with BAMM](https://github.com/OpenManufacturingPlatform/openmanufacturingplatform.github.io/raw/master/docs/sds/OMP-SDS-Product-Modeling-Whitepaper.pdf). Whitepaper. 2022-11-24. Open Manufacturing Platform. - [ESMF Documentation](https://eclipse-esmf.github.io/esmf-documentation/). Eclipse Semantic Modeling Framework. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0004-GovernanceProcess/CX-0004-GovernanceProcess.md b/versioned_docs/version-24.03/standards/CX-0004-GovernanceProcess/CX-0004-GovernanceProcess.md index 645495991..1fd09fc3b 100644 --- a/versioned_docs/version-24.03/standards/CX-0004-GovernanceProcess/CX-0004-GovernanceProcess.md +++ b/versioned_docs/version-24.03/standards/CX-0004-GovernanceProcess/CX-0004-GovernanceProcess.md @@ -1,4 +1,4 @@ -# CX-0004 Governance Process for Aspect models v.1.0.1 +# CX-0004 Governance Process for Aspect models v1.0.1 ## ABSTRACT @@ -195,3 +195,7 @@ https://github.com/eclipse-tractusx/sldt-semantic-models [^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf [^2]: https://catena-x.net/de/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0005-ItemRelationshipServiceAPI/CX-0005-ItemRelationshipServiceAPI.md b/versioned_docs/version-24.03/standards/CX-0005-ItemRelationshipServiceAPI/CX-0005-ItemRelationshipServiceAPI.md index 4b98d409c..7a6c60fad 100644 --- a/versioned_docs/version-24.03/standards/CX-0005-ItemRelationshipServiceAPI/CX-0005-ItemRelationshipServiceAPI.md +++ b/versioned_docs/version-24.03/standards/CX-0005-ItemRelationshipServiceAPI/CX-0005-ItemRelationshipServiceAPI.md @@ -255,3 +255,7 @@ represents a reference implementation that implements this standard. ```text [OPTIONAL] Add Tables here here if necessary. Please delete if no tables are provided ``` + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0006-RegistrationAndInitialOnboarding/CX-0006-RegistrationAndInitialOnboarding.md b/versioned_docs/version-24.03/standards/CX-0006-RegistrationAndInitialOnboarding/CX-0006-RegistrationAndInitialOnboarding.md index 75e5782a7..08d2953fa 100644 --- a/versioned_docs/version-24.03/standards/CX-0006-RegistrationAndInitialOnboarding/CX-0006-RegistrationAndInitialOnboarding.md +++ b/versioned_docs/version-24.03/standards/CX-0006-RegistrationAndInitialOnboarding/CX-0006-RegistrationAndInitialOnboarding.md @@ -1,5 +1,5 @@ -# CX-0006 Registration and Initial Onboarding v.1.1.3 +# CX-0006 Registration and Initial Onboarding v1.1.3 ## ABSTRACT @@ -355,3 +355,7 @@ presents a reference implementation that implements this standard. - Figure 1 High-level view of a section of Catena-X - Figure 2: Catena-X Registration Process - Figure 3: Exemplary registration flow using a Onboarding Service Provider + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0007-MinimalDataProviderServicesOffering/CX-0007-MinimalDataProviderServicesOffering.md b/versioned_docs/version-24.03/standards/CX-0007-MinimalDataProviderServicesOffering/CX-0007-MinimalDataProviderServicesOffering.md index 8c2ace7d0..5972f3bc6 100644 --- a/versioned_docs/version-24.03/standards/CX-0007-MinimalDataProviderServicesOffering/CX-0007-MinimalDataProviderServicesOffering.md +++ b/versioned_docs/version-24.03/standards/CX-0007-MinimalDataProviderServicesOffering/CX-0007-MinimalDataProviderServicesOffering.md @@ -1,5 +1,5 @@ -# CX-0007 Minimal Data Provider Service Offering v.1.0.2 +# CX-0007 Minimal Data Provider Service Offering v1.0.2 ## ABSTRACT @@ -478,3 +478,7 @@ As long as not specified differently, the latest version of the standard MUST be > *This section is non-normative* Example: The code found at https://github.com/eclipse-tractusx/dft-frontend in combination with https://github.com/eclipse-tractusx/dft-backend presents a reference implementation that implements this standard. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0008-RelevantStandardsForConformityAssessments/CX-0008-Relevantstandardsforconformityassessments.md b/versioned_docs/version-24.03/standards/CX-0008-RelevantStandardsForConformityAssessments/CX-0008-Relevantstandardsforconformityassessments.md index 83fcdc503..4b613b172 100644 --- a/versioned_docs/version-24.03/standards/CX-0008-RelevantStandardsForConformityAssessments/CX-0008-Relevantstandardsforconformityassessments.md +++ b/versioned_docs/version-24.03/standards/CX-0008-RelevantStandardsForConformityAssessments/CX-0008-Relevantstandardsforconformityassessments.md @@ -1,5 +1,5 @@ -# CX-0008 Relevant standards for conformity assessments v.1.1.0 +# CX-0008 Relevant standards for conformity assessments v1.1.0 ## ABSTRACT @@ -171,3 +171,7 @@ period until the guidelines become mandatory. ## REVISIONS & UPDATE - v1.1.0 Added ISO 27001 and/or TISAX Level 1 as alternative to ISO 9001 + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0009-CXRegistrationAPI/CX-0009-CXRegistrationAPI.md b/versioned_docs/version-24.03/standards/CX-0009-CXRegistrationAPI/CX-0009-CXRegistrationAPI.md index bc5ff032f..14b023b1b 100644 --- a/versioned_docs/version-24.03/standards/CX-0009-CXRegistrationAPI/CX-0009-CXRegistrationAPI.md +++ b/versioned_docs/version-24.03/standards/CX-0009-CXRegistrationAPI/CX-0009-CXRegistrationAPI.md @@ -1,5 +1,5 @@ -# CX-0009 CX Registration API v.1.1.3 +# CX-0009 CX Registration API v1.1.3 ## ABSTRACT @@ -399,3 +399,7 @@ endpoint: | 403 | Forbidden | | 405 | Method not allowed | | 409 | Error | + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0010-BusinessPartnerNumber/CX-0010-BusinessPartnerNumber.md b/versioned_docs/version-24.03/standards/CX-0010-BusinessPartnerNumber/CX-0010-BusinessPartnerNumber.md index 0b8e594e6..ad14727b9 100644 --- a/versioned_docs/version-24.03/standards/CX-0010-BusinessPartnerNumber/CX-0010-BusinessPartnerNumber.md +++ b/versioned_docs/version-24.03/standards/CX-0010-BusinessPartnerNumber/CX-0010-BusinessPartnerNumber.md @@ -207,3 +207,7 @@ Intentionally left blank. > *This section is non-normative* Intentionally left blank. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0011-IssuingAgency/CX-0011-IssuingAgency.md b/versioned_docs/version-24.03/standards/CX-0011-IssuingAgency/CX-0011-IssuingAgency.md index 2de1b8b8a..092eaf3ff 100644 --- a/versioned_docs/version-24.03/standards/CX-0011-IssuingAgency/CX-0011-IssuingAgency.md +++ b/versioned_docs/version-24.03/standards/CX-0011-IssuingAgency/CX-0011-IssuingAgency.md @@ -205,3 +205,7 @@ back. documentation](https://github.com/eclipse-tractusx/bpdm/blob/main/docs/arc42/architecture-documentation.adoc) 2. [BPDM use case on Catena-X Website](https://catena-x.net/en/angebote/bpdm) + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0012-BusinessPartnerDataPoolAPI/CX-0012-BusinessPartnerDataPoolAPI.md b/versioned_docs/version-24.03/standards/CX-0012-BusinessPartnerDataPoolAPI/CX-0012-BusinessPartnerDataPoolAPI.md index 4541b84fb..bca41075c 100644 --- a/versioned_docs/version-24.03/standards/CX-0012-BusinessPartnerDataPoolAPI/CX-0012-BusinessPartnerDataPoolAPI.md +++ b/versioned_docs/version-24.03/standards/CX-0012-BusinessPartnerDataPoolAPI/CX-0012-BusinessPartnerDataPoolAPI.md @@ -1,5 +1,5 @@ -# CX-0012 Business Partner Data Pool API v.3.0.0 +# CX-0012 Business Partner Data Pool API v3.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -535,3 +535,7 @@ Intentionally left blank. [^6]: The classification is subject to change. [^7]: Note that in case of a PUT the corresponding resources expect to receive the full updated record, including values that did not change. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0013-IdentityOfMemberCompanies/CX-0013-IdentityofMemberCompanies.md b/versioned_docs/version-24.03/standards/CX-0013-IdentityOfMemberCompanies/CX-0013-IdentityofMemberCompanies.md index 16590e84a..ace1505e1 100644 --- a/versioned_docs/version-24.03/standards/CX-0013-IdentityOfMemberCompanies/CX-0013-IdentityofMemberCompanies.md +++ b/versioned_docs/version-24.03/standards/CX-0013-IdentityOfMemberCompanies/CX-0013-IdentityofMemberCompanies.md @@ -166,3 +166,7 @@ The leading technical implementation of SSI evolves around the open standards of Figure 1: Overview of Open Standards for SSI Source: http://www.lifewithalacrity.com/2016/04/the-path-to-self-soverereign-identity.html + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0014-EmployeesAndTechnicalUsers/CX-0014-EmployeesAndTechnicalUsers.md b/versioned_docs/version-24.03/standards/CX-0014-EmployeesAndTechnicalUsers/CX-0014-EmployeesAndTechnicalUsers.md index 072da8603..caa4b6f2f 100644 --- a/versioned_docs/version-24.03/standards/CX-0014-EmployeesAndTechnicalUsers/CX-0014-EmployeesAndTechnicalUsers.md +++ b/versioned_docs/version-24.03/standards/CX-0014-EmployeesAndTechnicalUsers/CX-0014-EmployeesAndTechnicalUsers.md @@ -118,3 +118,7 @@ Hand this documentation to the conformity assessment body ### 3.1 Normative References - CX-0015 IAM & ACCESS CONTROL PARADIGM + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0016-CompanyAttributeVerification/CX-0016-CompanyAttributeVerification.md b/versioned_docs/version-24.03/standards/CX-0016-CompanyAttributeVerification/CX-0016-CompanyAttributeVerification.md index e7c022e90..abfd3f72e 100644 --- a/versioned_docs/version-24.03/standards/CX-0016-CompanyAttributeVerification/CX-0016-CompanyAttributeVerification.md +++ b/versioned_docs/version-24.03/standards/CX-0016-CompanyAttributeVerification/CX-0016-CompanyAttributeVerification.md @@ -205,3 +205,7 @@ Unlike the Business Partner Number and the Membership Credential, the Dismantler - CX-0011 ISSUING AGENCY - CX-0013 IDENTITY OF MEMBERS COMPANIES - CX-0014 IDENTITY OF EMPLOYEES AND TECHNICAL USERS + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0017-CompanyRoleByTheConnector/CX-0017-CompanyRoleByTheConnector.md b/versioned_docs/version-24.03/standards/CX-0017-CompanyRoleByTheConnector/CX-0017-CompanyRoleByTheConnector.md index 2acf4172f..18baa4ec5 100644 --- a/versioned_docs/version-24.03/standards/CX-0017-CompanyRoleByTheConnector/CX-0017-CompanyRoleByTheConnector.md +++ b/versioned_docs/version-24.03/standards/CX-0017-CompanyRoleByTheConnector/CX-0017-CompanyRoleByTheConnector.md @@ -136,3 +136,7 @@ The creation, signing and the exchange of this Verifiable Presentation is descri ```text This section is not applicable for this standard in this version. ``` + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0018-EclipseDataSpaceConnector/CX-0018-EclipseDataSpaceConnector.md b/versioned_docs/version-24.03/standards/CX-0018-EclipseDataSpaceConnector/CX-0018-EclipseDataSpaceConnector.md index e8434539e..ba332f011 100644 --- a/versioned_docs/version-24.03/standards/CX-0018-EclipseDataSpaceConnector/CX-0018-EclipseDataSpaceConnector.md +++ b/versioned_docs/version-24.03/standards/CX-0018-EclipseDataSpaceConnector/CX-0018-EclipseDataSpaceConnector.md @@ -671,3 +671,7 @@ Jarke, M., Otto, B., & Ram, S. (2019). *Data sovereignty and data space ecosyste ## 6 Resources CX-0018 Sovereign Data Exchange - Architecture.drawio + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0019-AspectModelSerialPartTypization/CX-0019-AspectModelSerialPartTypization.md b/versioned_docs/version-24.03/standards/CX-0019-AspectModelSerialPartTypization/CX-0019-AspectModelSerialPartTypization.md index 0b0b6177a..a6ef506d3 100644 --- a/versioned_docs/version-24.03/standards/CX-0019-AspectModelSerialPartTypization/CX-0019-AspectModelSerialPartTypization.md +++ b/versioned_docs/version-24.03/standards/CX-0019-AspectModelSerialPartTypization/CX-0019-AspectModelSerialPartTypization.md @@ -222,3 +222,7 @@ An AASX file can be generated from the RDF Turtle file. The AASX file defines on ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0020-AspectModelSingleLevelBoMAsBuilt/CX-0020-AspectModelSingleLevelBomAsBuilt.md b/versioned_docs/version-24.03/standards/CX-0020-AspectModelSingleLevelBoMAsBuilt/CX-0020-AspectModelSingleLevelBomAsBuilt.md index 817db5a89..9ade81355 100644 --- a/versioned_docs/version-24.03/standards/CX-0020-AspectModelSingleLevelBoMAsBuilt/CX-0020-AspectModelSingleLevelBomAsBuilt.md +++ b/versioned_docs/version-24.03/standards/CX-0020-AspectModelSingleLevelBoMAsBuilt/CX-0020-AspectModelSingleLevelBomAsBuilt.md @@ -1,4 +1,4 @@ -# CX-0020 Aspect Model SingleLevelBomAsBuilt v.2.0.0 +# CX-0020 Aspect Model SingleLevelBomAsBuilt v2.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -277,3 +277,7 @@ https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0021-AspectModelBatch/CX-0021-AspectModelBatch.md b/versioned_docs/version-24.03/standards/CX-0021-AspectModelBatch/CX-0021-AspectModelBatch.md index d636734ba..847286312 100644 --- a/versioned_docs/version-24.03/standards/CX-0021-AspectModelBatch/CX-0021-AspectModelBatch.md +++ b/versioned_docs/version-24.03/standards/CX-0021-AspectModelBatch/CX-0021-AspectModelBatch.md @@ -1,4 +1,4 @@ -# CX-0021 Aspect Model: Batch v.1.0.1 +# CX-0021 Aspect Model: Batch v1.0.1 ## ABSTRACT @@ -222,3 +222,7 @@ https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process [^4]: https://creativecommons.org/licenses/by/4.0/legalcode [^5]: https://github.com/eclipse-esmf/esmf-sdk + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0022-NotificationProcess/CX-0022-NotificationProcess.md b/versioned_docs/version-24.03/standards/CX-0022-NotificationProcess/CX-0022-NotificationProcess.md index d9b93f247..bdeb85500 100644 --- a/versioned_docs/version-24.03/standards/CX-0022-NotificationProcess/CX-0022-NotificationProcess.md +++ b/versioned_docs/version-24.03/standards/CX-0022-NotificationProcess/CX-0022-NotificationProcess.md @@ -1,5 +1,5 @@ -# CX-0022 Notification Process v.1.1.1 +# CX-0022 Notification Process v1.1.1 ## ABSTRACT @@ -231,3 +231,7 @@ Below, the UML sequence diagram to resolve a quality alert is depicted. - CX-0010 BUSINESS PARTNER NUMBER - CX-0002 DIGITAL TWINS IN CATENA-X - CX-0018 ECLIPSE DATA SPACE CONNECTOR (EDC) + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0023-NotificationAPI/CX-0023-NotificationAPI.md b/versioned_docs/version-24.03/standards/CX-0023-NotificationAPI/CX-0023-NotificationAPI.md index 784a034b5..af2e1c884 100644 --- a/versioned_docs/version-24.03/standards/CX-0023-NotificationAPI/CX-0023-NotificationAPI.md +++ b/versioned_docs/version-24.03/standards/CX-0023-NotificationAPI/CX-0023-NotificationAPI.md @@ -1,4 +1,4 @@ -# CX-0023 Notification API v.1.2.2 +# CX-0023 Notification API v1.2.2 ## ABSTRACT @@ -419,3 +419,7 @@ https://github.com/eclipse-tractusx/tractusx-edc [^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf [^2]: https://catena-x.net/de/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0026-ProductCarbonFootprintDataModel/CX-0026-ProductCarbonFootprintDataModel.md b/versioned_docs/version-24.03/standards/CX-0026-ProductCarbonFootprintDataModel/CX-0026-ProductCarbonFootprintDataModel.md index 821711d37..c646e8af8 100644 --- a/versioned_docs/version-24.03/standards/CX-0026-ProductCarbonFootprintDataModel/CX-0026-ProductCarbonFootprintDataModel.md +++ b/versioned_docs/version-24.03/standards/CX-0026-ProductCarbonFootprintDataModel/CX-0026-ProductCarbonFootprintDataModel.md @@ -1,4 +1,4 @@ -# CX-0026 Product Carbon Footprint Data Model v.2.0.0 +# CX-0026 Product Carbon Footprint Data Model v2.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -292,3 +292,7 @@ https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.pc ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0027-ProductCarbonFootprintAspectModel/CX-0027-ProductCarbonFootprintAspectModel.md b/versioned_docs/version-24.03/standards/CX-0027-ProductCarbonFootprintAspectModel/CX-0027-ProductCarbonFootprintAspectModel.md index 24fdf6a7a..c3cabc644 100644 --- a/versioned_docs/version-24.03/standards/CX-0027-ProductCarbonFootprintAspectModel/CX-0027-ProductCarbonFootprintAspectModel.md +++ b/versioned_docs/version-24.03/standards/CX-0027-ProductCarbonFootprintAspectModel/CX-0027-ProductCarbonFootprintAspectModel.md @@ -1,5 +1,5 @@ -# CX-0027 Product Carbon Footprint Aspect Model v.1.0.0 +# CX-0027 Product Carbon Footprint Aspect Model v1.0.0 ## 1. Introduction @@ -435,3 +435,7 @@ In addition to the technical representation of the semantic model through the li The BAMM Aspect Model Editor is open source and can be downloaded via the official website: [BAMM Aspect Model Editor Landing Page](https://www.bosch-connected-industry.com/de/de/downloads/aspect-model-editor) The official documentation and installation instructions can be accessed via the open manufacturing platform: [BAMM Documentation](https://openmanufacturingplatform.github.io/sds-documentation/ame-guide/4.0.2/introduction.html). + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0028-ProductCarbonFootprintRequestAPI/CX-0028-ProductCarbonFootprintRequestAPI.md b/versioned_docs/version-24.03/standards/CX-0028-ProductCarbonFootprintRequestAPI/CX-0028-ProductCarbonFootprintRequestAPI.md index f4af81f89..e24df7cf3 100644 --- a/versioned_docs/version-24.03/standards/CX-0028-ProductCarbonFootprintRequestAPI/CX-0028-ProductCarbonFootprintRequestAPI.md +++ b/versioned_docs/version-24.03/standards/CX-0028-ProductCarbonFootprintRequestAPI/CX-0028-ProductCarbonFootprintRequestAPI.md @@ -194,3 +194,7 @@ defined PCF dataset back to the quested consumer. [^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf [^2]: https://catena-x.net/de/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0030-DataModelBoMAsSpecified/CX-0030-DataModelBoMAsSpecified.md b/versioned_docs/version-24.03/standards/CX-0030-DataModelBoMAsSpecified/CX-0030-DataModelBoMAsSpecified.md index 4745e9f41..fee82a896 100644 --- a/versioned_docs/version-24.03/standards/CX-0030-DataModelBoMAsSpecified/CX-0030-DataModelBoMAsSpecified.md +++ b/versioned_docs/version-24.03/standards/CX-0030-DataModelBoMAsSpecified/CX-0030-DataModelBoMAsSpecified.md @@ -1,4 +1,4 @@ -# CX-0030 Aspect Model BoM As Specified v.2.0.0 +# CX-0030 Aspect Model BoM As Specified v2.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -229,3 +229,7 @@ So far no .md documentation can be generated. So it is recommended to not ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0031-DataModelMaterialForHomologation/CX-0031-DataModelMaterialForHomologation.md b/versioned_docs/version-24.03/standards/CX-0031-DataModelMaterialForHomologation/CX-0031-DataModelMaterialForHomologation.md new file mode 100644 index 000000000..42f552ec4 --- /dev/null +++ b/versioned_docs/version-24.03/standards/CX-0031-DataModelMaterialForHomologation/CX-0031-DataModelMaterialForHomologation.md @@ -0,0 +1,304 @@ + +# CX-0031 Data Model: Material For Homologation v1.1.1 + +## ABSTRACT + +The data model Material for Homologation describes the naming and classification of a material to be used in a RRR calculation according to [ISO 2262](#3-references). The values represent the material name, the standard that the material complies with and their respective VDA group according [VDA 231-106](#3-references). +The [VDA 231-106](#3-references)classification enables a reliable RRR calculation as each VDA group is is related to an [ISO 2262](#3-references) group. + +## 1. INTRODUCTION + +This document describes one semantic model used in the Catena-X network. + +### 1.1 AUDIENCE & SCOPE + +> *This section is non-normative* + +The standard is relevant for the following roles: + +- Data Provider / Consumer +- Business Application Provider +- Enablement Service Provider + +### 1.2 CONTEXT + +> *This section is non-normative* + +The standard “materialforhomologation” is meant as an enhancement for the material information of a vehicle and its components. As soon as it comes to the calculation of RRR quotas according RRR-Directive 2005/64/EC in combination with [ISO 22628](#3-references) it is necessary to assigned materials of vehicle to an ISO group mentioned in [ISO 22628](#3-references). To achieve this it is required to use specific standards to be able to identify materials in a reliable way. The standard “materialforhomologation” enables this. + +### 1.3 CONFORMANCE + +As well as sections marked as non-normative, all authoring guidelines, diagrams, +examples, and notes in this specification are non-normative. Everything else in +this specification is normative. + +The key words **MAY**, **MUST**, **MUST NOT**, **OPTIONAL**, **RECOMMENDED**, +**REQUIRED**, **SHOULD** and **SHOULD NOT** in this document document are to be +interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they +appear in all capitals, as shown here. + +### 1.4 PROOF OF CONFORMITY + +> *This section is non-normative* + +All participants and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs). + +- To proof conformity with the materialforhomologation Semantic Model Standard check your json file against the json schema. +- Every data provider of materialforhomologation data MUST provide the data conformant to the semantic model specified in this document. +- The unique identifier of the semantic model specified in this document MUST be used by the data provider to define the semantics of the data being transferred. +- Every certified business application relying on materialforhomologation data MUST be able to consume data conformant to the semantic model specified in this document. +- This semantic model MUST be made available in the central Semantic Hub. + +The proof of conformity for a single semantic model is done according to the general rules for proving the conformity of data provided to a semantic model or the ability to consume the corresponding data. + +### 1.5 EXAMPLES + +```json +{"materialForHomologation": +[{"vdaStandardId":{"mainGroup":"1","subgroup":"1.1"}, + "name":"WTSt 37-2", + "standard":"SEW 087 : 1981-06", + "itemNumber":"1.l.222.3333", + "share":20.1, + "materialNumber":"1.8960"} +``` + +### 1.6 TERMINOLOGY + +> *This section is non-normative* + +**vdaStandardID:** +The standard [ISO 2262](#3-references) assigns materials into specific groups like Metals, fluids, etc…. The VDA recommendation [VDA 231-106](#3-references) uses similar but more granular groups. vdaStandardID represents the [VDA 231-106](#3-references) group for each specific material. + +**name:** +The name of the material as named by the manufacturer of this material. +The data type is string. + +**Standard:** +The material classification usually follows a specific standard like SEW 087 for steel applicatons. +The data type is string. + +**materialNumber:** +The material number represents the naming or identification number of the material according to the mentioned standard in the field “standard”. +The data type is string. + +**itemNumber:** +The item number represents part number or identification number of the respective part. +The data type is string. + +**share:** +The share represents the share of the mentioned material in relation to the component. +The data type is double. + +**Aspect Model:** +A formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect. + +Additional terminology used in this standard can be looked up in the glossary on +the association homepage. + +: Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model. + +: Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). + +Additional terminology used in this standard can be looked up in the glossary on the association homepage. + +## 2 ASPECT MODEL “MATERIALFORHOMOLOGATION” + +### 2.1 INTRODUCTION + +The aspect model material for homologation assigns materials clearly to material groups that are used to calculate a reliable RRR-calculation according to RRR Directice 2005/64/EC in combination with [ISO 2262](#3-references). + +### 2.2 SPECIFICATION ARTIFACTS + +The modeling of the semantic model specified in this document was done in accordance to the "semantic driven workflow" to create a submodel template specification [SMT](#32-non-normative-references). + +This aspect model is written in SAMM 2.0.0 as a modeling language conformant to CX-0003 +as input for the semantic deriven workflow. + +Like all Catena-X data models, this model is available in a machine-readable format on GitHub +conformant to CX-0003. + +### 2.3 LICENSE + +This Catena-X data model is an outcome of Catena-X use case group R-Strategy Assistant. +This Catena-X data model is made available under the terms of the Creative Commons Attribution +4.0 International (CC-BY-4.0) license, which is available at Creative Commons4F4F. + +### 2.4 IDENTIFER OF SEMANTIC MODEL + +The semantic model has the unique identifier: + +```text + urn_bamm_io.catenax.material_for_homologation_1.0.0 +``` + +This identifier MUST be used by the data provider to define the semantics of the data being transferred. + +### 2.5 FORMATS OF SEMANTIC MODEL + +#### 2.5.1 RDF Turtle + +The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. + The corresponding TTL-file for the aspect model can be accessed via the following link [MaterialforHomologation](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.material_for_homologation/1.0.0/MaterialForHomologation.ttl) + +Please note that the linked version contains the semantic model’s latest version at the time of publication of this standard. However, it is possible that minor functional adjustments (noticeable by increments of the middle number of the version number: 1.0.0) or bug fixes - downward compatible - (noticeable by increments of the last number of the version number: 1.0.X) have been added in the meantime. Such updated or adjusted versions are not explicitly linked, as they do not require a new standardization document and were not available at the time of the publication of this standard. Accordingly, it is recommended to look for the updated semantic model in eclipse-tractusx/sldt-semantic-models repository and to use the updated version instead, as it brings important bug fixes or even additional functionalities. + +The open source command line tool of the Eclipse Semantic Modeling Framework is used for generation +of other file formats like for example a JSON Schema, aasx for Asset Administration Shell Submodel +Template or a HTML documentation. + +#### 2.5.2 JSON Schema + +A JSON Schema can be generated from the RDF Turtle file. The JSON Schema defines the Value-Only +payload of the Asset Administration Shell for the API operation "GetSubmodel". + +```json +{ + "$schema": "http://json-schema.org/draft-04/schema", + "type": "object", + "components": { + "schemas": { + "urn_bamm_io.catenax.material_for_homologation_1.0.0_ItemNumber1Trait": { + "type": "string", + "maxLength": 200 + }, + "urn_bamm_io.catenax.material_for_homologation_1.0.0_ShareCharacteristic": { + "type": "number" + }, + "urn_bamm_io.catenax.material_for_homologation_1.0.0_MainGroupTrait1": { + "type": "string", + "maxLength": 2 + }, + "urn_bamm_io.catenax.material_for_homologation_1.0.0_SubgroupTrait1": { + "type": "string", + "maxLength": 3 + }, + "urn_bamm_io.catenax.material_for_homologation_1.0.0_VDAStandardIdCharacteristic": { + "type": "object", + "properties": { + "mainGroup": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.material_for_homologation_1.0.0_MainGroupTrait1" + }, + "subgroup": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.material_for_homologation_1.0.0_SubgroupTrait1" + } + }, + "required": [ + "mainGroup", + "subgroup" + ] + }, + "urn_bamm_io.catenax.material_for_homologation_1.0.0_NameTrait1": { + "type": "string", + "maxLength": 50 + }, + "urn_bamm_io.catenax.material_for_homologation_1.0.0_StandardTrait1": { + "type": "string", + "maxLength": 20 + }, + "urn_bamm_io.catenax.material_for_homologation_1.0.0_MaterialNumberTrait1": { + "type": "string", + "maxLength": 20 + }, + "urn_bamm_io.catenax.material_for_homologation_1.0.0_MaterialForHomologationEntity": { + "type": "object", + "properties": { + "itemNumber": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.material_for_homologation_1.0.0_ItemNumber1Trait" + }, + "share": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.material_for_homologation_1.0.0_ShareCharacteristic" + }, + "vdaStandardId": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.material_for_homologation_1.0.0_VDAStandardIdCharacteristic" + }, + "name": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.material_for_homologation_1.0.0_NameTrait1" + }, + "standard": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.material_for_homologation_1.0.0_StandardTrait1" + }, + "materialNumber": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.material_for_homologation_1.0.0_MaterialNumberTrait1" + } + }, + "required": [ + "itemNumber", + "share", + "vdaStandardId", + "name", + "standard", + "materialNumber" + ] + }, + "urn_bamm_io.catenax.material_for_homologation_1.0.0_MaterialForHomologationCharacteristic": { + "type": "array", + "items": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.material_for_homologation_1.0.0_MaterialForHomologationEntity" + }, + "uniqueItems": true + } + } + }, + "properties": { + "materialForHomologation": { + "$ref": "#/components/schemas/urn_bamm_io.catenax.material_for_homologation_1.0.0_MaterialForHomologationCharacteristic" + } + }, + "required": [ + "materialForHomologation" + ] +} +``` + +#### 2.5.3 aasx + +An AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested +artifacts for a Submodel Template Specification conformant to \[[SMT](#32-non-normative-references)]. + +Note: As soon as the specification V3.0 of the Asset Administration Shell specfication is available +an update will be provided. + +## 3 REFERENCES + +### 3.1 NORMATIVE REFERENCES + +[CX-0002 Digital Twins in Catena-X V1.0.1](https://catena-x.net/de/standard-library) + +[CX-0003 Semantic Aspect Meta Model V1.0.2](https://catena-x.net/de/standard-library) + +[CX-0004 Governance Process for Semantic Models V1.0.1](https://catena-x.net/de/standard-library) + +[CX-0018 Eclipse Data Space Connector V1.0.1](https://catena-x.net/de/standard-library) + +[CX-0001 EDC Discovery API, Version 1.0.1](https://catena-x.net/de/standard-library) + +[ISO 22628 RRR-Calculation](https://www.iso.org/standard/35061.html) + +[VDA 231-106](https://webshop.vda.de/VDA/de/vda-231-106-102021) + +### 3.2 NON-NORMATIVE REFERENCES + +> *This section is non-normative* + +[SMT](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf) How to create a submodel template specification. Guideline. + +### 3.3 REFERENCE IMPLEMENTATIONS + +> *This section is non-normative* + +## ANNEXES + +### FIGURES + +> *This section is non-normative* + +![Semantic Model](./assets/MaterialforHomologation.png) + +### TABLES + +> *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0032-DataModelPartAsSpecified/CX-0032-DataModelPartAsSpecified.md b/versioned_docs/version-24.03/standards/CX-0032-DataModelPartAsSpecified/CX-0032-DataModelPartAsSpecified.md index f8768f66c..334576138 100644 --- a/versioned_docs/version-24.03/standards/CX-0032-DataModelPartAsSpecified/CX-0032-DataModelPartAsSpecified.md +++ b/versioned_docs/version-24.03/standards/CX-0032-DataModelPartAsSpecified/CX-0032-DataModelPartAsSpecified.md @@ -1,4 +1,3 @@ - # CX-0032 Data Model: Part As Specified v1.0.1 ## ABSTRACT @@ -203,3 +202,7 @@ The data model is described in BAMM 2.0.0. A html documentation can be generated > *This section is non-normative* ![PartAsSpecified](./assets/image.png) + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0033-DataModelReturnRequest/CX-0033-DataModelReturnRequest.md b/versioned_docs/version-24.03/standards/CX-0033-DataModelReturnRequest/CX-0033-DataModelReturnRequest.md index 0a0eb9193..693aee623 100644 --- a/versioned_docs/version-24.03/standards/CX-0033-DataModelReturnRequest/CX-0033-DataModelReturnRequest.md +++ b/versioned_docs/version-24.03/standards/CX-0033-DataModelReturnRequest/CX-0033-DataModelReturnRequest.md @@ -233,3 +233,7 @@ The following references refer to related Catena-X reference implementations and [^4]: https://creativecommons.org/licenses/by/4.0/legalcode [^5]: https://github.com/eclipse-esmf/esmf-sdk + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0034-DataModelBatteryPass/CX-0034-DataModelBatteryPass.md b/versioned_docs/version-24.03/standards/CX-0034-DataModelBatteryPass/CX-0034-DataModelBatteryPass.md index 67919e20a..70ec8b075 100644 --- a/versioned_docs/version-24.03/standards/CX-0034-DataModelBatteryPass/CX-0034-DataModelBatteryPass.md +++ b/versioned_docs/version-24.03/standards/CX-0034-DataModelBatteryPass/CX-0034-DataModelBatteryPass.md @@ -1,5 +1,5 @@ -# CX-0034 Data Model Battery Pass v.2.0.0 +# CX-0034 Data Model Battery Pass v2.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -187,3 +187,7 @@ A reference implementation of an application using or providing data conformant ### FIGURES ### TABLES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0035-DataModelMarketplaceoffer/CX-0035-DataModelMarketplaceoffer.md b/versioned_docs/version-24.03/standards/CX-0035-DataModelMarketplaceoffer/CX-0035-DataModelMarketplaceoffer.md index fb2b78680..c6fae7e0a 100644 --- a/versioned_docs/version-24.03/standards/CX-0035-DataModelMarketplaceoffer/CX-0035-DataModelMarketplaceoffer.md +++ b/versioned_docs/version-24.03/standards/CX-0035-DataModelMarketplaceoffer/CX-0035-DataModelMarketplaceoffer.md @@ -164,3 +164,7 @@ R-strategy: R-strategies serve to change the companies’ business mod-els in th [^4]: https://openmanufacturingplatform.github.io/ [^5]: https://internationaldataspaces.org/we/the-association/ + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0036-AspectModelQualityTask/CX-0036-AspectModelQualityTask.md b/versioned_docs/version-24.03/standards/CX-0036-AspectModelQualityTask/CX-0036-AspectModelQualityTask.md index 9693f3641..73a247f08 100644 --- a/versioned_docs/version-24.03/standards/CX-0036-AspectModelQualityTask/CX-0036-AspectModelQualityTask.md +++ b/versioned_docs/version-24.03/standards/CX-0036-AspectModelQualityTask/CX-0036-AspectModelQualityTask.md @@ -207,3 +207,7 @@ JSON schema. [^4]: https://creativecommons.org/licenses/by/4.0/legalcode [^5]: https://github.com/eclipse-esmf/esmf-sdk + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0037-AspectModelVehicleProductDescription/CX-0037-AspectModelVehicleProductDescription.md b/versioned_docs/version-24.03/standards/CX-0037-AspectModelVehicleProductDescription/CX-0037-AspectModelVehicleProductDescription.md index 28bb320d0..ed40bd018 100644 --- a/versioned_docs/version-24.03/standards/CX-0037-AspectModelVehicleProductDescription/CX-0037-AspectModelVehicleProductDescription.md +++ b/versioned_docs/version-24.03/standards/CX-0037-AspectModelVehicleProductDescription/CX-0037-AspectModelVehicleProductDescription.md @@ -271,3 +271,7 @@ CX - 0092 Aspect Model: QualityTaskAttachment [^4]: https://creativecommons.org/licenses/by/4.0/legalcode [^5]: https://github.com/eclipse-esmf/esmf-sdk#samm-cli + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0038-AspectModelFleetDiagnosticData/CX-0038-AspectModelFleetDiagnosticData.md b/versioned_docs/version-24.03/standards/CX-0038-AspectModelFleetDiagnosticData/CX-0038-AspectModelFleetDiagnosticData.md index 2cc6bd09d..e774fb393 100644 --- a/versioned_docs/version-24.03/standards/CX-0038-AspectModelFleetDiagnosticData/CX-0038-AspectModelFleetDiagnosticData.md +++ b/versioned_docs/version-24.03/standards/CX-0038-AspectModelFleetDiagnosticData/CX-0038-AspectModelFleetDiagnosticData.md @@ -259,3 +259,7 @@ JSON schema. [^4]: https://creativecommons.org/licenses/by/4.0/legalcode [^5]: https://github.com/eclipse-esmf/esmf-sdk + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0039-AspectModelFleetClaimData/CX-0039-AspectModelFleetClaimData.md b/versioned_docs/version-24.03/standards/CX-0039-AspectModelFleetClaimData/CX-0039-AspectModelFleetClaimData.md index b6c04b64f..774cea600 100644 --- a/versioned_docs/version-24.03/standards/CX-0039-AspectModelFleetClaimData/CX-0039-AspectModelFleetClaimData.md +++ b/versioned_docs/version-24.03/standards/CX-0039-AspectModelFleetClaimData/CX-0039-AspectModelFleetClaimData.md @@ -235,3 +235,7 @@ JSON schema. [^4]: https://creativecommons.org/licenses/by/4.0/legalcode [^5]: https://github.com/eclipse-esmf/esmf-sdk + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0040-AspectModelPartAnalyses/CX-0040-AspectModelPartAnalyses.md b/versioned_docs/version-24.03/standards/CX-0040-AspectModelPartAnalyses/CX-0040-AspectModelPartAnalyses.md index 3ed900d80..ccf1a6b2b 100644 --- a/versioned_docs/version-24.03/standards/CX-0040-AspectModelPartAnalyses/CX-0040-AspectModelPartAnalyses.md +++ b/versioned_docs/version-24.03/standards/CX-0040-AspectModelPartAnalyses/CX-0040-AspectModelPartAnalyses.md @@ -229,3 +229,7 @@ CX - 0092 Aspect Model: QualityTaskAttachment [^4]: https://creativecommons.org/licenses/by/4.0/legalcode [^5]: https://github.com/eclipse-esmf/esmf-sdk#samm-cli + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0041-AspectModelManufacturedPartsQualityInformation/CX-0041-AspectModelManufacturedPartsQualityInformation.md b/versioned_docs/version-24.03/standards/CX-0041-AspectModelManufacturedPartsQualityInformation/CX-0041-AspectModelManufacturedPartsQualityInformation.md index 88e275bed..dbaa8438f 100644 --- a/versioned_docs/version-24.03/standards/CX-0041-AspectModelManufacturedPartsQualityInformation/CX-0041-AspectModelManufacturedPartsQualityInformation.md +++ b/versioned_docs/version-24.03/standards/CX-0041-AspectModelManufacturedPartsQualityInformation/CX-0041-AspectModelManufacturedPartsQualityInformation.md @@ -243,3 +243,7 @@ JSON schema. [^4]: https://creativecommons.org/licenses/by/4.0/legalcode [^5]: https://github.com/eclipse-esmf/esmf-sdk + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0042-AspectModelSingleLevelBoMasPlanned/CX-0042-AspectModelSingleLevelBoMasPlanned.md b/versioned_docs/version-24.03/standards/CX-0042-AspectModelSingleLevelBoMasPlanned/CX-0042-AspectModelSingleLevelBoMasPlanned.md index 6262098f1..128e4ffe0 100644 --- a/versioned_docs/version-24.03/standards/CX-0042-AspectModelSingleLevelBoMasPlanned/CX-0042-AspectModelSingleLevelBoMasPlanned.md +++ b/versioned_docs/version-24.03/standards/CX-0042-AspectModelSingleLevelBoMasPlanned/CX-0042-AspectModelSingleLevelBoMasPlanned.md @@ -1,4 +1,4 @@ -# CX-0042 Aspect Model SingleLevelBomAsPlanned v.2.0.0 +# CX-0042 Aspect Model SingleLevelBomAsPlanned v2.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -211,3 +211,7 @@ This section is empty. ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0043-AspectModelPartAsPlanned/CX-0043-AspectModelPartAsPlanned.md b/versioned_docs/version-24.03/standards/CX-0043-AspectModelPartAsPlanned/CX-0043-AspectModelPartAsPlanned.md index 37cfdf75e..d9a98eb13 100644 --- a/versioned_docs/version-24.03/standards/CX-0043-AspectModelPartAsPlanned/CX-0043-AspectModelPartAsPlanned.md +++ b/versioned_docs/version-24.03/standards/CX-0043-AspectModelPartAsPlanned/CX-0043-AspectModelPartAsPlanned.md @@ -245,3 +245,7 @@ Shell specfication is available and update will be provided. [^4]: https://creativecommons.org/licenses/by/4.0/legalcode [^5]: https://github.com/eclipse-esmf/esmf-sdk + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0044-ECLASS/CX-0044-ECLASS.md b/versioned_docs/version-24.03/standards/CX-0044-ECLASS/CX-0044-ECLASS.md index 76e6672e5..c6c179a5f 100644 --- a/versioned_docs/version-24.03/standards/CX-0044-ECLASS/CX-0044-ECLASS.md +++ b/versioned_docs/version-24.03/standards/CX-0044-ECLASS/CX-0044-ECLASS.md @@ -270,3 +270,7 @@ be found on the respective webpage[^12]. [^11]: https://eclass.eu [^12]: https://eclass.eu/shop/en/product/eclass-13-0-asset + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0045-AspectModelDataChainTemplate/CX-0045-AspectModelDataChainTemplate.md b/versioned_docs/version-24.03/standards/CX-0045-AspectModelDataChainTemplate/CX-0045-AspectModelDataChainTemplate.md index 5df8a9204..1ac274827 100644 --- a/versioned_docs/version-24.03/standards/CX-0045-AspectModelDataChainTemplate/CX-0045-AspectModelDataChainTemplate.md +++ b/versioned_docs/version-24.03/standards/CX-0045-AspectModelDataChainTemplate/CX-0045-AspectModelDataChainTemplate.md @@ -1,4 +1,4 @@ -# CX - 0045 Data Chain Template v.1.2.0 +# CX - 0045 Data Chain Template v1.2.0 ## ABSTRACT @@ -316,3 +316,7 @@ not applicable > *This section is non-normative* not applicable + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic.md b/versioned_docs/version-24.03/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic.md index b71b45033..196c5c83f 100644 --- a/versioned_docs/version-24.03/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic.md +++ b/versioned_docs/version-24.03/standards/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic/CX-0046-DemandAndCapacityManagementProcessAndCoreBusinessLogic.md @@ -616,3 +616,7 @@ responsibilities. | **Quantum** | ZP | page | Blatt | - | pg | | **Mechanic** | KWH | kilowatt hour | Kilowattstunde | kW·h | kwh | | **(blank)** | | | | | xxx | + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup.md b/versioned_docs/version-24.03/standards/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup.md index b8fc50ed2..272707dd2 100644 --- a/versioned_docs/version-24.03/standards/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup.md +++ b/versioned_docs/version-24.03/standards/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup/CX-0047-DemandAndCapacityManagementDataModelMaterialDemandAndCapacityGroup.md @@ -448,3 +448,7 @@ Not applicable. > *This section is non-normative* Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup.md b/versioned_docs/version-24.03/standards/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup.md index 115c25db6..4d399e9a6 100644 --- a/versioned_docs/version-24.03/standards/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup.md +++ b/versioned_docs/version-24.03/standards/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup/CX-0048-DemandAndCapacityManagementAPIMaterialDemandAndCapacityGroup.md @@ -795,3 +795,7 @@ Not applicable. > *This section is non-normative* Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0049-DIDDocumentSchema/CX-0049-DIDDocumentSchema.md b/versioned_docs/version-24.03/standards/CX-0049-DIDDocumentSchema/CX-0049-DIDDocumentSchema.md index 0c990be25..73ab986c1 100644 --- a/versioned_docs/version-24.03/standards/CX-0049-DIDDocumentSchema/CX-0049-DIDDocumentSchema.md +++ b/versioned_docs/version-24.03/standards/CX-0049-DIDDocumentSchema/CX-0049-DIDDocumentSchema.md @@ -127,3 +127,7 @@ W3C DID document properties [https://www.w3.org/TR/did-spec-registries/#did-docu > *This section is non-normative* Managed Identity Wallet which supports the **did:web** method: https://github.com/catenax-ng/tx-managed-identity-wallets/tree/features/java-did-web + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0050-FrameworkAgreementCredential/CX-0050-FrameworkAgreementCredential.md b/versioned_docs/version-24.03/standards/CX-0050-FrameworkAgreementCredential/CX-0050-FrameworkAgreementCredential.md index 8577b3b28..0e706ed4b 100644 --- a/versioned_docs/version-24.03/standards/CX-0050-FrameworkAgreementCredential/CX-0050-FrameworkAgreementCredential.md +++ b/versioned_docs/version-24.03/standards/CX-0050-FrameworkAgreementCredential/CX-0050-FrameworkAgreementCredential.md @@ -338,3 +338,8 @@ Content: "contractVersion": "1.0.0", } } +```` + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0051-SummaryCredential/CX-0051-SummaryCredential.md b/versioned_docs/version-24.03/standards/CX-0051-SummaryCredential/CX-0051-SummaryCredential.md index c7b8fa175..bb8260cd9 100644 --- a/versioned_docs/version-24.03/standards/CX-0051-SummaryCredential/CX-0051-SummaryCredential.md +++ b/versioned_docs/version-24.03/standards/CX-0051-SummaryCredential/CX-0051-SummaryCredential.md @@ -190,3 +190,7 @@ This section is not applicable for this standard in this version. ```text This section is not applicable for this standard in this version. ``` + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0052-AspectModelManufacturingCapability/CX-0052-AspectModelManufacturingCapability.md b/versioned_docs/version-24.03/standards/CX-0052-AspectModelManufacturingCapability/CX-0052-AspectModelManufacturingCapability.md index c1712d81a..d0ec9d179 100644 --- a/versioned_docs/version-24.03/standards/CX-0052-AspectModelManufacturingCapability/CX-0052-AspectModelManufacturingCapability.md +++ b/versioned_docs/version-24.03/standards/CX-0052-AspectModelManufacturingCapability/CX-0052-AspectModelManufacturingCapability.md @@ -1,4 +1,4 @@ -# CX - 0052 Aspect Model "ManufacturingCapability" v.1.0.0 +# CX - 0052 Aspect Model "ManufacturingCapability" v1.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -313,3 +313,7 @@ Not applicable. > *This section is non-normative* Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0053-BPNDiscoveryServiceAPIs/CX-0053-BPNDiscoveryServiceAPIs.md b/versioned_docs/version-24.03/standards/CX-0053-BPNDiscoveryServiceAPIs/CX-0053-BPNDiscoveryServiceAPIs.md index 77d7feef4..eb15b5ae0 100644 --- a/versioned_docs/version-24.03/standards/CX-0053-BPNDiscoveryServiceAPIs/CX-0053-BPNDiscoveryServiceAPIs.md +++ b/versioned_docs/version-24.03/standards/CX-0053-BPNDiscoveryServiceAPIs/CX-0053-BPNDiscoveryServiceAPIs.md @@ -200,3 +200,7 @@ https://github.com/eclipse-tractusx/sldt-discovery-finder This is a reference implementation for the BPN Discovery Service: https://github.com/eclipse-tractusx/sldt-bpn-discovery + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0054-ApplicationServiceRelease/CX-0054-ApplicationServiceRelease.md b/versioned_docs/version-24.03/standards/CX-0054-ApplicationServiceRelease/CX-0054-ApplicationServiceRelease.md index caba4aa73..d0fabdbfd 100644 --- a/versioned_docs/version-24.03/standards/CX-0054-ApplicationServiceRelease/CX-0054-ApplicationServiceRelease.md +++ b/versioned_docs/version-24.03/standards/CX-0054-ApplicationServiceRelease/CX-0054-ApplicationServiceRelease.md @@ -363,3 +363,7 @@ The image found below depicts an example Service Detail Input Page that implemen The json api description found in [openpi json file](./assets/swagger.json) presents a reference API that implements this standard. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0055-DataProcessingPatternsforITSystemIntegration/CX-0055-DataProcessingPatternsforITSystemIntegration.md b/versioned_docs/version-24.03/standards/CX-0055-DataProcessingPatternsforITSystemIntegration/CX-0055-DataProcessingPatternsforITSystemIntegration.md index afe9310dc..09157be8c 100644 --- a/versioned_docs/version-24.03/standards/CX-0055-DataProcessingPatternsforITSystemIntegration/CX-0055-DataProcessingPatternsforITSystemIntegration.md +++ b/versioned_docs/version-24.03/standards/CX-0055-DataProcessingPatternsforITSystemIntegration/CX-0055-DataProcessingPatternsforITSystemIntegration.md @@ -138,7 +138,7 @@ This includes, but is not limited to the following use-cases: **Data Processing Pattern 2** (Knowledge Agents): All solutions that shall be used for data provisioning/data consumption for use-cases using Knowledge Agents MUST implement the following standards: -- CX-0084 Federated Queries in Data Spaces (Knowledge Agents) v.1.0.0 +- CX-0084 Federated Queries in Data Spaces (Knowledge Agents) v1.0.0 This includes, but is not limited to the following use-cases: @@ -157,6 +157,10 @@ the data provider to provide the data in the correct semantic modelling language - CX–0018 Sovereign Data Exchange v 1.0.1 - CX-0002 Digital Twins in Catena-X v 1.0.2 - CX-0003 SAMM Aspect Meta Model v 1.0.2 -- CX-0084 Federated Queries in Data Spaces (Knowledge Agents) v.1.0.0 +- CX-0084 Federated Queries in Data Spaces (Knowledge Agents) v1.0.0 ## ANNEXES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0056-SemanticModelClassifiedLoadSpectrum/CX-0056-SemanticModelClassifiedLoadSpectrum.md b/versioned_docs/version-24.03/standards/CX-0056-SemanticModelClassifiedLoadSpectrum/CX-0056-SemanticModelClassifiedLoadSpectrum.md index b5838ec6f..059777d0b 100644 --- a/versioned_docs/version-24.03/standards/CX-0056-SemanticModelClassifiedLoadSpectrum/CX-0056-SemanticModelClassifiedLoadSpectrum.md +++ b/versioned_docs/version-24.03/standards/CX-0056-SemanticModelClassifiedLoadSpectrum/CX-0056-SemanticModelClassifiedLoadSpectrum.md @@ -262,3 +262,7 @@ The data model is described in SAMM. A html documentation can be generated from ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0057-SemanticModelRemainingUsefulLife/CX-0057-SemanticModelRemainingUsefulLife.md b/versioned_docs/version-24.03/standards/CX-0057-SemanticModelRemainingUsefulLife/CX-0057-SemanticModelRemainingUsefulLife.md index 2004bbda3..d6a8577ca 100644 --- a/versioned_docs/version-24.03/standards/CX-0057-SemanticModelRemainingUsefulLife/CX-0057-SemanticModelRemainingUsefulLife.md +++ b/versioned_docs/version-24.03/standards/CX-0057-SemanticModelRemainingUsefulLife/CX-0057-SemanticModelRemainingUsefulLife.md @@ -208,3 +208,7 @@ The data model is described in SAMM6. A html documentation can be generated from ```text [OPTIONAL] Add Tables here if necessary ``` + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0058-APIEndurancePredictor/CX-0058-APIEndurancePredictor.md b/versioned_docs/version-24.03/standards/CX-0058-APIEndurancePredictor/CX-0058-APIEndurancePredictor.md index c6ec7cca0..e8fc27877 100644 --- a/versioned_docs/version-24.03/standards/CX-0058-APIEndurancePredictor/CX-0058-APIEndurancePredictor.md +++ b/versioned_docs/version-24.03/standards/CX-0058-APIEndurancePredictor/CX-0058-APIEndurancePredictor.md @@ -309,3 +309,7 @@ The following http response codes MUST be defined for HTTP POST endpoint for the ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0059-TriangleBehavioralTwinEndurancePredictorService/CX-0059-TriangleBehavioralTwinEndurancePredictorService.md b/versioned_docs/version-24.03/standards/CX-0059-TriangleBehavioralTwinEndurancePredictorService/CX-0059-TriangleBehavioralTwinEndurancePredictorService.md index 53bb03019..1410f62be 100644 --- a/versioned_docs/version-24.03/standards/CX-0059-TriangleBehavioralTwinEndurancePredictorService/CX-0059-TriangleBehavioralTwinEndurancePredictorService.md +++ b/versioned_docs/version-24.03/standards/CX-0059-TriangleBehavioralTwinEndurancePredictorService/CX-0059-TriangleBehavioralTwinEndurancePredictorService.md @@ -1,4 +1,4 @@ -# CX-0059 Use Case Behavioral Twin Endurance Predictor v.1.2.0 +# CX-0059 Use Case Behavioral Twin Endurance Predictor v1.2.0 ## ABSTRACT @@ -693,3 +693,7 @@ The following http response codes MUST be defined for HTTP POST endpoint for the ### 5.3 REFERENCE IMPLEMENTATIONS > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0060-TriangleTraceabilityDigitalTwinAsBuilt/CX-0060-TriangleTraceabilityDigitalTwinAsBuilt.md b/versioned_docs/version-24.03/standards/CX-0060-TriangleTraceabilityDigitalTwinAsBuilt/CX-0060-TriangleTraceabilityDigitalTwinAsBuilt.md index 0e12dc001..d2eefe82f 100644 --- a/versioned_docs/version-24.03/standards/CX-0060-TriangleTraceabilityDigitalTwinAsBuilt/CX-0060-TriangleTraceabilityDigitalTwinAsBuilt.md +++ b/versioned_docs/version-24.03/standards/CX-0060-TriangleTraceabilityDigitalTwinAsBuilt/CX-0060-TriangleTraceabilityDigitalTwinAsBuilt.md @@ -212,3 +212,7 @@ The traceability KIT and sub-KITs will include further information on EDC data a ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0061-TriangleTraceabilityDataProvisioningDigitalTwinAsPlanned/CX-0061-TriangleTraceabilityDataProvisioningDigitalTwinAsPlanned.md b/versioned_docs/version-24.03/standards/CX-0061-TriangleTraceabilityDataProvisioningDigitalTwinAsPlanned/CX-0061-TriangleTraceabilityDataProvisioningDigitalTwinAsPlanned.md index 29993ae05..196ad4ed5 100644 --- a/versioned_docs/version-24.03/standards/CX-0061-TriangleTraceabilityDataProvisioningDigitalTwinAsPlanned/CX-0061-TriangleTraceabilityDataProvisioningDigitalTwinAsPlanned.md +++ b/versioned_docs/version-24.03/standards/CX-0061-TriangleTraceabilityDataProvisioningDigitalTwinAsPlanned/CX-0061-TriangleTraceabilityDataProvisioningDigitalTwinAsPlanned.md @@ -192,3 +192,7 @@ The traceability KIT and sub-KITs will include further information on EDC data a ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0062-TriangleTraceabilityNotifications/CX-0062-TriangleTraceabilityNotifications.md b/versioned_docs/version-24.03/standards/CX-0062-TriangleTraceabilityNotifications/CX-0062-TriangleTraceabilityNotifications.md index 67fc2e51e..e3854d138 100644 --- a/versioned_docs/version-24.03/standards/CX-0062-TriangleTraceabilityNotifications/CX-0062-TriangleTraceabilityNotifications.md +++ b/versioned_docs/version-24.03/standards/CX-0062-TriangleTraceabilityNotifications/CX-0062-TriangleTraceabilityNotifications.md @@ -126,3 +126,7 @@ The traceability KIT and sub-KITs will include further information on EDC data a ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0063-TriangleForProductCarbonFootprintRequest/CX-0063-TriangleForProductCarbonFootprintRequest.md b/versioned_docs/version-24.03/standards/CX-0063-TriangleForProductCarbonFootprintRequest/CX-0063-TriangleForProductCarbonFootprintRequest.md index 9df24ece8..bfa34ce7d 100644 --- a/versioned_docs/version-24.03/standards/CX-0063-TriangleForProductCarbonFootprintRequest/CX-0063-TriangleForProductCarbonFootprintRequest.md +++ b/versioned_docs/version-24.03/standards/CX-0063-TriangleForProductCarbonFootprintRequest/CX-0063-TriangleForProductCarbonFootprintRequest.md @@ -1,4 +1,4 @@ -# CX-0063 Triangle for Product Carbon Footprint Request v.2.1.0 +# CX-0063 Triangle for Product Carbon Footprint Request v2.1.0 ## ABSTRACT @@ -371,3 +371,7 @@ Currently the reference implementation is no FOSS application. It was implemente [Architectural Overview](./assets/ArchitecturalOverview.png) ### TABLES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0065-TriangleForDismantlingService/CX-0065-TriangleForDismantlingService.md b/versioned_docs/version-24.03/standards/CX-0065-TriangleForDismantlingService/CX-0065-TriangleForDismantlingService.md index 7d3bd5ace..97e5b3ab7 100644 --- a/versioned_docs/version-24.03/standards/CX-0065-TriangleForDismantlingService/CX-0065-TriangleForDismantlingService.md +++ b/versioned_docs/version-24.03/standards/CX-0065-TriangleForDismantlingService/CX-0065-TriangleForDismantlingService.md @@ -322,3 +322,7 @@ VP<--DD: visualize dismantling information | R3\_ReadDisplay | The data provided in the circular economy use case as well as by and for related business applications such as Batterypass application, Marketplace, Circularity Cockpit and R-Strategy Assistant shall only be displayed to the data user and read by applications for circular economy usages such as R-Strategy logic calculations or support of buying decisions by the data user. The end-user confirms that the data is not used for analytic purposes out side the circular economy scope such as analyzing consumer behavior based on load cycles or analyzing the number of produced cars or components by a company. It also not allowed to print the data or distributed it to third parties. | | R3\_ExchangeOfAnonymousData | The data exchanged in the use case is focused on non-personal related data. Therefore, data provider confirm, that they only provide anonymized data to data consumers or that the data is anonymized in the data transfer. | | R3\_ExchangePartner | Data is only exchanged between partners, that have signed a bilateral contract to exchange the data. Therefore, data consumers are only allowed to consume data once their legal entity has signed a respective contract. | + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0066-AspectModelEndofLifeofVehicleCompliance/CX-0066-AspectModelEndofLifeofVehicleCompliance.md b/versioned_docs/version-24.03/standards/CX-0066-AspectModelEndofLifeofVehicleCompliance/CX-0066-AspectModelEndofLifeofVehicleCompliance.md index 344b1909d..c7f7cfb6c 100644 --- a/versioned_docs/version-24.03/standards/CX-0066-AspectModelEndofLifeofVehicleCompliance/CX-0066-AspectModelEndofLifeofVehicleCompliance.md +++ b/versioned_docs/version-24.03/standards/CX-0066-AspectModelEndofLifeofVehicleCompliance/CX-0066-AspectModelEndofLifeofVehicleCompliance.md @@ -601,3 +601,7 @@ VDA 231-106 - https://webshop.vda.de/VDA/de/vda-231-106-102021 ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0067-OntologyModelsinCatenaX/CX-0067-OntologyModelsinCatenaX.md b/versioned_docs/version-24.03/standards/CX-0067-OntologyModelsinCatenaX/CX-0067-OntologyModelsinCatenaX.md index a075fdc4d..5d5d11453 100644 --- a/versioned_docs/version-24.03/standards/CX-0067-OntologyModelsinCatenaX/CX-0067-OntologyModelsinCatenaX.md +++ b/versioned_docs/version-24.03/standards/CX-0067-OntologyModelsinCatenaX/CX-0067-OntologyModelsinCatenaX.md @@ -1,4 +1,4 @@ -# CX-0067 Ontology Models to realize federated query in Catena-X v.1.0.0 +# CX-0067 Ontology Models to realize federated query in Catena-X v1.0.0 ## ABSTRACT @@ -536,3 +536,7 @@ Syntactic modeling guidelines increase comprehensibility and enable unified mode ```text [OPTIONAL] Add Tables here here if necessary. Please delete if no tables are provided ``` + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0068-MPShopFloorInformationServiceAPI/CX-0068-MPShopFloorInformationServiceAPI.md b/versioned_docs/version-24.03/standards/CX-0068-MPShopFloorInformationServiceAPI/CX-0068-MPShopFloorInformationServiceAPI.md index e6a656649..5206f0a05 100644 --- a/versioned_docs/version-24.03/standards/CX-0068-MPShopFloorInformationServiceAPI/CX-0068-MPShopFloorInformationServiceAPI.md +++ b/versioned_docs/version-24.03/standards/CX-0068-MPShopFloorInformationServiceAPI/CX-0068-MPShopFloorInformationServiceAPI.md @@ -42,7 +42,7 @@ Namely: - *ProvideProductionForecastInformation* uses "ProvideProductionForecast" data model The unsubscribe call has no corresponding data model, as it is a simple HTTP DELETE. -The JSON string is standardized in document (MP) CX - 0069 Shop-Floor-Information-Service Aspect Model v.1.0.0. +The JSON string is standardized in document (MP) CX - 0069 Shop-Floor-Information-Service Aspect Model v1.0.0. The standard only describes the sending and receiving of Shop-Floor-Information-data through EDC. The object is created and handled by applications of the companies involved, but these applications are not part of the standard. ### 1.3 CONFORMANCE AND PROOF OF CONFORMITY @@ -702,3 +702,7 @@ Every API endpoint defined in Chapter 2.2.1 MUST respond to incoming requests wi ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0069-AspectModelMPShopFloorInformationService/CX-0069-AspectModelMPShopFloorInformationService.md b/versioned_docs/version-24.03/standards/CX-0069-AspectModelMPShopFloorInformationService/CX-0069-AspectModelMPShopFloorInformationService.md index f2a6f1bcf..142484fee 100644 --- a/versioned_docs/version-24.03/standards/CX-0069-AspectModelMPShopFloorInformationService/CX-0069-AspectModelMPShopFloorInformationService.md +++ b/versioned_docs/version-24.03/standards/CX-0069-AspectModelMPShopFloorInformationService/CX-0069-AspectModelMPShopFloorInformationService.md @@ -1,4 +1,4 @@ -# CX-0069 Shop-Floor-Information-Service Aspect Model v.1.0.0 +# CX-0069 Shop-Floor-Information-Service Aspect Model v1.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -504,3 +504,7 @@ EnumTimeUnits MUST be one of the following items: unit:secondUnitOfTime, unit:mi ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0070-AssetTrackingPlatformAPIStandardization/CX-0070-AssetTrackingPlatformAPIStandardization.md b/versioned_docs/version-24.03/standards/CX-0070-AssetTrackingPlatformAPIStandardization/CX-0070-AssetTrackingPlatformAPIStandardization.md index 8232bc118..9898d01b1 100644 --- a/versioned_docs/version-24.03/standards/CX-0070-AssetTrackingPlatformAPIStandardization/CX-0070-AssetTrackingPlatformAPIStandardization.md +++ b/versioned_docs/version-24.03/standards/CX-0070-AssetTrackingPlatformAPIStandardization/CX-0070-AssetTrackingPlatformAPIStandardization.md @@ -1003,10 +1003,10 @@ In case of an error, one of the following responses can occur: > *This section is normative* -CX-0002 Digital Twins in Catena-X v.2.0.0 -CX-0018 Eclipse Data Space Connector (EDC) v.2.1.0 -CX-0083 Aspect Model IoTSensorDeviceDefinition v.1.0.0 -CX-0106 Aspect Model IoTSensorData v.1.0.0 +CX-0002 Digital Twins in Catena-X v2.0.0 +CX-0018 Eclipse Data Space Connector (EDC) v2.1.0 +CX-0083 Aspect Model IoTSensorDeviceDefinition v1.0.0 +CX-0106 Aspect Model IoTSensorData v1.0.0 CX-0105 Asset Tracking Triangle Document v1.0.0 ### 3.2 NON-NORMATIVE REFERENCES @@ -1026,3 +1026,7 @@ CX-0105 Asset Tracking Triangle Document v1.0.0 ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0071-TriangleQualityEarlyWarningFieldandRootCause/CX-0071-TriangleQualityEarlyWarningFieldandRootCause.md b/versioned_docs/version-24.03/standards/CX-0071-TriangleQualityEarlyWarningFieldandRootCause/CX-0071-TriangleQualityEarlyWarningFieldandRootCause.md index 4f1c2487c..7de86d99e 100644 --- a/versioned_docs/version-24.03/standards/CX-0071-TriangleQualityEarlyWarningFieldandRootCause/CX-0071-TriangleQualityEarlyWarningFieldandRootCause.md +++ b/versioned_docs/version-24.03/standards/CX-0071-TriangleQualityEarlyWarningFieldandRootCause/CX-0071-TriangleQualityEarlyWarningFieldandRootCause.md @@ -93,7 +93,7 @@ Additional terminology used in this standard can be looked up in the glossary on In order to participate in the Catena-X use case "Quality - Early Warning Field" and "Quality - Root Cause analysis" the following single standards **MUST** be fulfilled by all participants: -CX - 0018 Eclipse Data Connector(EDC) v.2.0.0 +CX - 0018 Eclipse Data Connector(EDC) v2.0.0 As OEM data provider I **MUST** align to the following aspect models in the corresponding data exchange: @@ -149,3 +149,7 @@ CX - 0092 Aspect Model: QualityTaskAttachment ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0072-OSimProcessAndCoreBusinessLogic/CX-0072-OSimProcessAndCoreBusinessLogic.md b/versioned_docs/version-24.03/standards/CX-0072-OSimProcessAndCoreBusinessLogic/CX-0072-OSimProcessAndCoreBusinessLogic.md index 550a0e7e7..8e3437477 100644 --- a/versioned_docs/version-24.03/standards/CX-0072-OSimProcessAndCoreBusinessLogic/CX-0072-OSimProcessAndCoreBusinessLogic.md +++ b/versioned_docs/version-24.03/standards/CX-0072-OSimProcessAndCoreBusinessLogic/CX-0072-OSimProcessAndCoreBusinessLogic.md @@ -217,3 +217,7 @@ n.a. ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0073-OSimAPI/CX-0073-OSimAPI.md b/versioned_docs/version-24.03/standards/CX-0073-OSimAPI/CX-0073-OSimAPI.md index faf467e1a..5cb8f48b7 100644 --- a/versioned_docs/version-24.03/standards/CX-0073-OSimAPI/CX-0073-OSimAPI.md +++ b/versioned_docs/version-24.03/standards/CX-0073-OSimAPI/CX-0073-OSimAPI.md @@ -534,3 +534,7 @@ SemVer – Semantic Versioning 2.0.0 https://semver.org/ > *This section is non-normative* ## ANNEXES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0074-BusinessPartnerGateAPI/CX-0074-BusinessPartnerGateAPI.md b/versioned_docs/version-24.03/standards/CX-0074-BusinessPartnerGateAPI/CX-0074-BusinessPartnerGateAPI.md index cc60ede42..23444eb62 100644 --- a/versioned_docs/version-24.03/standards/CX-0074-BusinessPartnerGateAPI/CX-0074-BusinessPartnerGateAPI.md +++ b/versioned_docs/version-24.03/standards/CX-0074-BusinessPartnerGateAPI/CX-0074-BusinessPartnerGateAPI.md @@ -1,4 +1,4 @@ -# CX-0074 Business Partner Data GATE API v.2.0.0 +# CX-0074 Business Partner Data GATE API v2.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -464,3 +464,7 @@ Intentionally left blank. [^4]: The classification is subject to change. [^5]: Note that in case of a PUT the corresponding resources expect to receive the full updated record, including values that did not change. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0075-MPShopFloorInformationServiceProcessandCoreBusinessLogic/CX-0075-MPShopFloorInformationServiceProcessandCoreBusinessLogic.md b/versioned_docs/version-24.03/standards/CX-0075-MPShopFloorInformationServiceProcessandCoreBusinessLogic/CX-0075-MPShopFloorInformationServiceProcessandCoreBusinessLogic.md index c3796e16a..e443a3608 100644 --- a/versioned_docs/version-24.03/standards/CX-0075-MPShopFloorInformationServiceProcessandCoreBusinessLogic/CX-0075-MPShopFloorInformationServiceProcessandCoreBusinessLogic.md +++ b/versioned_docs/version-24.03/standards/CX-0075-MPShopFloorInformationServiceProcessandCoreBusinessLogic/CX-0075-MPShopFloorInformationServiceProcessandCoreBusinessLogic.md @@ -1,5 +1,5 @@ -# CX-0075 Shop-Floor-Information-Service Process v.1.0.0 +# CX-0075 Shop-Floor-Information-Service Process v1.0.0 ## ABSTRACT @@ -45,7 +45,7 @@ Namely: The *unsubscribe* call has no corresponding data model, as it is a simple HTTP DELETE. -The JSON string is standardized in document (MP) CX - 0069 Shop-Floor-Information-Service Aspect Model v.1.0.0. +The JSON string is standardized in document (MP) CX - 0069 Shop-Floor-Information-Service Aspect Model v1.0.0. The standard only describes the sending and receiving of Shop-Floor-Information-data through EDC. The object is created and handled by applications of the companies involved, but these applications are not part of the standard. ### 1.3 CONFORMANCE AND PROOF OF CONFORMITY @@ -156,3 +156,7 @@ n.a. ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0076-GoldenRecordEndtoEndRequirementsStandard/CX-0076-GoldenRecordEndtoEndRequirementsStandard.md b/versioned_docs/version-24.03/standards/CX-0076-GoldenRecordEndtoEndRequirementsStandard/CX-0076-GoldenRecordEndtoEndRequirementsStandard.md index 7c029f13c..6a2e4c87d 100644 --- a/versioned_docs/version-24.03/standards/CX-0076-GoldenRecordEndtoEndRequirementsStandard/CX-0076-GoldenRecordEndtoEndRequirementsStandard.md +++ b/versioned_docs/version-24.03/standards/CX-0076-GoldenRecordEndtoEndRequirementsStandard/CX-0076-GoldenRecordEndtoEndRequirementsStandard.md @@ -1,4 +1,4 @@ -# CX-0076 - GoldenRecordEndtoEndRequirementsStandard v.1.0.0 +# CX-0076 - GoldenRecordEndtoEndRequirementsStandard v1.0.0 ## ABSTRACT @@ -341,3 +341,7 @@ Intentionally left blank. [^4]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf [^5]: https://catena-x.net/de/standardisierung/catena-x-einfuehren-umsetzen/standardisierung/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0077-DataQualityDashboard/CX-0077-DataQualityDashboard.md b/versioned_docs/version-24.03/standards/CX-0077-DataQualityDashboard/CX-0077-DataQualityDashboard.md index 657902913..def239bf9 100644 --- a/versioned_docs/version-24.03/standards/CX-0077-DataQualityDashboard/CX-0077-DataQualityDashboard.md +++ b/versioned_docs/version-24.03/standards/CX-0077-DataQualityDashboard/CX-0077-DataQualityDashboard.md @@ -1,4 +1,4 @@ -# CX-0077 Data Quality Dashboard v.1.1.0 +# CX-0077 Data Quality Dashboard v1.1.0 ## ABSTRACT @@ -7,7 +7,7 @@ which is the basis of the Golden Record Process and secure the syntactical and l DQD has to visualize the outcome of the data quality rules via a dashboard. -DQD uses the Gate API CX-0074_V.1.1.0 or higher and the Pool API CX-0012_V.1.0.0 +DQD uses the Gate API CX-0074_v1.1.0 or higher and the Pool API CX-0012_v1.0.0 or higher for pulling BP data records. DQD is a client/ server cloud application which contains a Web Client and a Cloud Server Application. DQD has to contain a user and authorization management capability aligned with the CX Portal and Marketplace user management. DQD intends to support the EDC Asset function capability and has to be available in English and German language. @@ -351,3 +351,7 @@ Intentionally left blank. [^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf [^2]: https://catena-x.net/de/standardisierung/catena-x-einfuehren-umsetzen/standardisierung/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0078-BankDataVerificationDashboard/CX-0078-BankDataVerificationDashboard.md b/versioned_docs/version-24.03/standards/CX-0078-BankDataVerificationDashboard/CX-0078-BankDataVerificationDashboard.md index afe3d5e55..c0bb505c7 100644 --- a/versioned_docs/version-24.03/standards/CX-0078-BankDataVerificationDashboard/CX-0078-BankDataVerificationDashboard.md +++ b/versioned_docs/version-24.03/standards/CX-0078-BankDataVerificationDashboard/CX-0078-BankDataVerificationDashboard.md @@ -8,7 +8,7 @@ The Bank Data Verification Dashboard (BDV) has to rely on a set of clearly defin BDV has to visualize the outcome of the banking verification rules via a dashboard. There a user should be able to compare the input and output of banking data quality after the BDV verification process ended. -BDV has to use the Gate API CX-0074\_V.1.1.0 or higher for synchronization of CX Member BP data records with the CX Member banking data. The CX Member banking data has to be send via the BDV API. The results of the BDV verification have to be stored in the BDV Logfile and should get pulled via the BDV API from the CX Member systems. +BDV has to use the Gate API CX-0074\_v1.1.0 or higher for synchronization of CX Member BP data records with the CX Member banking data. The CX Member banking data has to be send via the BDV API. The results of the BDV verification have to be stored in the BDV Logfile and should get pulled via the BDV API from the CX Member systems. BDV has to be a client/ server cloud application which has to contain a Web Client and a Cloud Servicer Application. BDV has to contain a user and authorization management capability aligned with the CX Portal and Marketplace user management. BDV has to support the EDC Asset function capability and has to be available in English and German language. @@ -302,3 +302,7 @@ Intentionally left blank. [^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf [^2]: https://catena-x.net/de/standardisierung/catena-x-einfuehren-umsetzen/standardisierung/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0079-NaturalPersonScreeningDashboard/CX-0079-NaturalPersonScreeningDashboard.md b/versioned_docs/version-24.03/standards/CX-0079-NaturalPersonScreeningDashboard/CX-0079-NaturalPersonScreeningDashboard.md index b667faa7b..ee6824a83 100644 --- a/versioned_docs/version-24.03/standards/CX-0079-NaturalPersonScreeningDashboard/CX-0079-NaturalPersonScreeningDashboard.md +++ b/versioned_docs/version-24.03/standards/CX-0079-NaturalPersonScreeningDashboard/CX-0079-NaturalPersonScreeningDashboard.md @@ -411,3 +411,7 @@ Intentionally left blank. > This section is non-normative Intentionally left blank. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0080-BPDMFraudPreventionService/CX-0080-BPDMFraudPreventionService.md b/versioned_docs/version-24.03/standards/CX-0080-BPDMFraudPreventionService/CX-0080-BPDMFraudPreventionService.md index 3a79f14cf..7060f60a5 100644 --- a/versioned_docs/version-24.03/standards/CX-0080-BPDMFraudPreventionService/CX-0080-BPDMFraudPreventionService.md +++ b/versioned_docs/version-24.03/standards/CX-0080-BPDMFraudPreventionService/CX-0080-BPDMFraudPreventionService.md @@ -230,3 +230,7 @@ Intentionally left blank. [^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf [^2]: https://catena-x.net/de/standardisierung/catena-x-einfuehren-umsetzen/standardisierung/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0081-BPDMCountryRisk/CX-0081-BPDMCountryRisk.md b/versioned_docs/version-24.03/standards/CX-0081-BPDMCountryRisk/CX-0081-BPDMCountryRisk.md index 193b41a14..21c2b02d7 100644 --- a/versioned_docs/version-24.03/standards/CX-0081-BPDMCountryRisk/CX-0081-BPDMCountryRisk.md +++ b/versioned_docs/version-24.03/standards/CX-0081-BPDMCountryRisk/CX-0081-BPDMCountryRisk.md @@ -1,5 +1,5 @@ -# CX-0081 Country Risk API v.1.1.0 +# CX-0081 Country Risk API v1.1.0 ## ABSTRACT @@ -389,3 +389,7 @@ Reserved for future use. > *This section is non-normative.* Reserved for future use. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0083-AspectModelIoTSensorDeviceDefinition/CX-0083-AspectModelIoTSensorDeviceDefinition.md b/versioned_docs/version-24.03/standards/CX-0083-AspectModelIoTSensorDeviceDefinition/CX-0083-AspectModelIoTSensorDeviceDefinition.md index a7038a807..cbe46ccc7 100644 --- a/versioned_docs/version-24.03/standards/CX-0083-AspectModelIoTSensorDeviceDefinition/CX-0083-AspectModelIoTSensorDeviceDefinition.md +++ b/versioned_docs/version-24.03/standards/CX-0083-AspectModelIoTSensorDeviceDefinition/CX-0083-AspectModelIoTSensorDeviceDefinition.md @@ -1,4 +1,4 @@ -# CX-0083 Aspect Model IotSensorDeviceDefinition v.1.0.0 +# CX-0083 Aspect Model IotSensorDeviceDefinition v1.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -92,7 +92,7 @@ A BPN is the unique identifier of a partner within Catena-X Additional terminology used in this standard can be looked up in the glossary on the association homepage. -## 2 ASPECT MODEL “IotSensorDeviceDefinition v.2.0.0” +## 2 ASPECT MODEL “IotSensorDeviceDefinition v2.0.0” > *This section is normative* @@ -175,3 +175,7 @@ https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.io ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0084-FederatedQueriesInDataSpaces/CX-0084-FederatedQueriesInDataSpaces.md b/versioned_docs/version-24.03/standards/CX-0084-FederatedQueriesInDataSpaces/CX-0084-FederatedQueriesInDataSpaces.md index ee91f773e..dda873721 100644 --- a/versioned_docs/version-24.03/standards/CX-0084-FederatedQueriesInDataSpaces/CX-0084-FederatedQueriesInDataSpaces.md +++ b/versioned_docs/version-24.03/standards/CX-0084-FederatedQueriesInDataSpaces/CX-0084-FederatedQueriesInDataSpaces.md @@ -1414,3 +1414,7 @@ The "dataAddress" part for Skill Assets consists of the following properties. | edc:proxyMethod | yes | must be set to “true” | true | | edc:proxyQueryParams | yes | must be set to "true" | true | | edc:proxyBody | yes | must be set to "true" | true‚ | + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0085-PurisAspectModelProductStock/CX-0085-PurisAspectModelProductStock.md b/versioned_docs/version-24.03/standards/CX-0085-PurisAspectModelProductStock/CX-0085-PurisAspectModelProductStock.md index fce99dbfc..eb9ae807d 100644 --- a/versioned_docs/version-24.03/standards/CX-0085-PurisAspectModelProductStock/CX-0085-PurisAspectModelProductStock.md +++ b/versioned_docs/version-24.03/standards/CX-0085-PurisAspectModelProductStock/CX-0085-PurisAspectModelProductStock.md @@ -269,3 +269,7 @@ Not applicable. > *This section is non-normative* Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0086-PurisProductStockExchangeAPI/CX-0086-PurisProductStockExchangeAPI.md b/versioned_docs/version-24.03/standards/CX-0086-PurisProductStockExchangeAPI/CX-0086-PurisProductStockExchangeAPI.md index f5b7f7f20..f521256ce 100644 --- a/versioned_docs/version-24.03/standards/CX-0086-PurisProductStockExchangeAPI/CX-0086-PurisProductStockExchangeAPI.md +++ b/versioned_docs/version-24.03/standards/CX-0086-PurisProductStockExchangeAPI/CX-0086-PurisProductStockExchangeAPI.md @@ -769,3 +769,7 @@ Not applicable. > *This section is non-normative* Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0087-OSimDataModelMaterialFlowSimulationResult/CX-0087-OSimDataModelMaterialFlowSimulationResult.md b/versioned_docs/version-24.03/standards/CX-0087-OSimDataModelMaterialFlowSimulationResult/CX-0087-OSimDataModelMaterialFlowSimulationResult.md index 5ae217100..0f3fc1eb5 100644 --- a/versioned_docs/version-24.03/standards/CX-0087-OSimDataModelMaterialFlowSimulationResult/CX-0087-OSimDataModelMaterialFlowSimulationResult.md +++ b/versioned_docs/version-24.03/standards/CX-0087-OSimDataModelMaterialFlowSimulationResult/CX-0087-OSimDataModelMaterialFlowSimulationResult.md @@ -320,3 +320,7 @@ CX-0073 OSim API ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0088-AspectModelUserEstimatedLoading/CX-0088-AspectModelUserEstimatedLoading.md b/versioned_docs/version-24.03/standards/CX-0088-AspectModelUserEstimatedLoading/CX-0088-AspectModelUserEstimatedLoading.md index 11b2dbd19..09b7c0eae 100644 --- a/versioned_docs/version-24.03/standards/CX-0088-AspectModelUserEstimatedLoading/CX-0088-AspectModelUserEstimatedLoading.md +++ b/versioned_docs/version-24.03/standards/CX-0088-AspectModelUserEstimatedLoading/CX-0088-AspectModelUserEstimatedLoading.md @@ -297,3 +297,7 @@ CX–0018 ECLIPSE DATA SPACE CONNECTOR (EDC), Version 2.0.0 ```text [OPTIONAL] Add Tables here if necessary ``` + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0089-TriangleBehavioralTwinEnduranceEstimatorService/CX-0089-TriangleBehavioralTwinEnduranceEstimatorServic.md b/versioned_docs/version-24.03/standards/CX-0089-TriangleBehavioralTwinEnduranceEstimatorService/CX-0089-TriangleBehavioralTwinEnduranceEstimatorService.md similarity index 98% rename from versioned_docs/version-24.03/standards/CX-0089-TriangleBehavioralTwinEnduranceEstimatorService/CX-0089-TriangleBehavioralTwinEnduranceEstimatorServic.md rename to versioned_docs/version-24.03/standards/CX-0089-TriangleBehavioralTwinEnduranceEstimatorService/CX-0089-TriangleBehavioralTwinEnduranceEstimatorService.md index 9bee592c0..345e93458 100644 --- a/versioned_docs/version-24.03/standards/CX-0089-TriangleBehavioralTwinEnduranceEstimatorService/CX-0089-TriangleBehavioralTwinEnduranceEstimatorServic.md +++ b/versioned_docs/version-24.03/standards/CX-0089-TriangleBehavioralTwinEnduranceEstimatorService/CX-0089-TriangleBehavioralTwinEnduranceEstimatorService.md @@ -129,3 +129,7 @@ To participate in the Triangle Behavioural Twin Endurance Predictor, the followi ### FIGURES ### TABLES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0090-APIEnduranceEstimator/CX-0090-APIEnduranceEstimator.md b/versioned_docs/version-24.03/standards/CX-0090-APIEnduranceEstimator/CX-0090-APIEnduranceEstimator.md index 8eaf839ca..5e78609ce 100644 --- a/versioned_docs/version-24.03/standards/CX-0090-APIEnduranceEstimator/CX-0090-APIEnduranceEstimator.md +++ b/versioned_docs/version-24.03/standards/CX-0090-APIEnduranceEstimator/CX-0090-APIEnduranceEstimator.md @@ -319,3 +319,7 @@ The following http response codes MUST be defined for HTTP POST endpoint for the ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0091-AspectModelFleetVehicles/CX-0091-AspectModelFleetVehicles.md b/versioned_docs/version-24.03/standards/CX-0091-AspectModelFleetVehicles/CX-0091-AspectModelFleetVehicles.md index 818f50fc1..d9918d209 100644 --- a/versioned_docs/version-24.03/standards/CX-0091-AspectModelFleetVehicles/CX-0091-AspectModelFleetVehicles.md +++ b/versioned_docs/version-24.03/standards/CX-0091-AspectModelFleetVehicles/CX-0091-AspectModelFleetVehicles.md @@ -225,7 +225,7 @@ This semantic model has the unique identifier: urn:samm:io.catenax.fleet.vehicles:1.0.0 This model has an external reference to -CX - 0037 Aspect Model Vehicle Product Description v.2.0.0 +CX - 0037 Aspect Model Vehicle Product Description v2.0.0 with unique identifier urn:samm:io.catenax.vehicle.product_description:3.0.0 ### 2.5 Formats of Semantic Model @@ -272,3 +272,7 @@ CX-0092 Aspect Model: QualityTaskAttachment [^4]: https://creativecommons.org/licenses/by/4.0/legalcode [^5]: https://github.com/eclipse-esmf/esmf-sdk#samm-cli + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0092-AspectModelQualityTaskAttachment/CX-0092-AspectModelQualityTaskAttachment.md b/versioned_docs/version-24.03/standards/CX-0092-AspectModelQualityTaskAttachment/CX-0092-AspectModelQualityTaskAttachment.md index 33337159f..d621f8b86 100644 --- a/versioned_docs/version-24.03/standards/CX-0092-AspectModelQualityTaskAttachment/CX-0092-AspectModelQualityTaskAttachment.md +++ b/versioned_docs/version-24.03/standards/CX-0092-AspectModelQualityTaskAttachment/CX-0092-AspectModelQualityTaskAttachment.md @@ -245,3 +245,7 @@ JSON schema. [^1]: https://creativecommons.org/licenses/by/4.0/legalcode [^2]: https://github.com/eclipse-esmf/esmf-sdk + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0093-AspectModelTractionBatteryCode/CX-0093-AspectModelTractionBatteryCode.md b/versioned_docs/version-24.03/standards/CX-0093-AspectModelTractionBatteryCode/CX-0093-AspectModelTractionBatteryCode.md index c906b8d5b..9016838f3 100644 --- a/versioned_docs/version-24.03/standards/CX-0093-AspectModelTractionBatteryCode/CX-0093-AspectModelTractionBatteryCode.md +++ b/versioned_docs/version-24.03/standards/CX-0093-AspectModelTractionBatteryCode/CX-0093-AspectModelTractionBatteryCode.md @@ -229,3 +229,7 @@ CX-0018 ECLPISE DATA SPACE CONNECTOR (EDC) ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0094-AspectModelPartSiteInformationAsPlanned/CX-0094-AspectModelPartSiteInformationAsPlanned.md b/versioned_docs/version-24.03/standards/CX-0094-AspectModelPartSiteInformationAsPlanned/CX-0094-AspectModelPartSiteInformationAsPlanned.md index d4aacefa8..4be1bf51e 100644 --- a/versioned_docs/version-24.03/standards/CX-0094-AspectModelPartSiteInformationAsPlanned/CX-0094-AspectModelPartSiteInformationAsPlanned.md +++ b/versioned_docs/version-24.03/standards/CX-0094-AspectModelPartSiteInformationAsPlanned/CX-0094-AspectModelPartSiteInformationAsPlanned.md @@ -1,4 +1,4 @@ -# CX-0094 Aspect Model: Part Site In Formation As Planned v.1.0.0 +# CX-0094 Aspect Model: Part Site In Formation As Planned v1.0.0 ## ABSTRACT @@ -207,3 +207,7 @@ CX-0018 ECLPISE DATA SPACE CONNECTOR (EDC) ```text [OPTIONAL] Add Tables here here if nececarry ``` + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0095-DataModelTransmissionPass/CX-0095-DataModelTransmissionPass.md b/versioned_docs/version-24.03/standards/CX-0095-DataModelTransmissionPass/CX-0095-DataModelTransmissionPass.md index cc9cddd29..006f5e7b5 100644 --- a/versioned_docs/version-24.03/standards/CX-0095-DataModelTransmissionPass/CX-0095-DataModelTransmissionPass.md +++ b/versioned_docs/version-24.03/standards/CX-0095-DataModelTransmissionPass/CX-0095-DataModelTransmissionPass.md @@ -329,3 +329,7 @@ and update will be provided. ### FIGURES ![Data Model](./assets/image.png) + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0096-TriangleForDigitalProductPass/CX-0096-TriangleForDigitalProductPass.md b/versioned_docs/version-24.03/standards/CX-0096-TriangleForDigitalProductPass/CX-0096-TriangleForDigitalProductPass.md index 5d8a9e1bd..c357becdc 100644 --- a/versioned_docs/version-24.03/standards/CX-0096-TriangleForDigitalProductPass/CX-0096-TriangleForDigitalProductPass.md +++ b/versioned_docs/version-24.03/standards/CX-0096-TriangleForDigitalProductPass/CX-0096-TriangleForDigitalProductPass.md @@ -122,19 +122,19 @@ To participate in the digital product passport use case, the following single st be fulfilled by all participants for which the standard is relevant: - [CX-0001 EDC Discovery API](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0001-EDCDiscoveryAPI_v1.0.2.pdf) -- [CX-0002 Digital Twins in Catena - X](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0002-DigitalTwinsInCatenaX-v.2.0.0.pdf) -- [CX-0003 SAMM Semantic Aspect Meta Model](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Archiv/Update_Juli_23_R_3.2/CX-0003-SAMMSemanticAspectMetaModel-v.1.0.2.pdf) +- [CX-0002 Digital Twins in Catena - X](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0002-DigitalTwinsInCatenaX-v2.0.0.pdf) +- [CX-0003 SAMM Semantic Aspect Meta Model](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Archiv/Update_Juli_23_R_3.2/CX-0003-SAMMSemanticAspectMetaModel-v1.0.2.pdf) - [CX-0006 Registration and initial onboarding](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0006-RegistrationAndInitialOnboarding-1.1.2.pdf) - [CX-0008 Relevant standards for conformity assessments](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/6_Onboarding/CX_-_0008_Conformity_Assessment_PlatformCapabilityOnboarding_v_1.0.1.pdf) -- [CX-0013 Identity of Member Companies](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0013-IdentityofMemberCompanies-v.1.1.0.pdf) +- [CX-0013 Identity of Member Companies](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0013-IdentityofMemberCompanies-v1.1.0.pdf) - [CX-0014 Employees and Technical Users](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/4_IAM/CX_-_0014_Employees_and_Technical_Users_PlatformCapabilityIAM_v_1.0.1.pdf) - [CX-0015 IAM & Access Control Paradigm](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/4_IAM/CX_-_0015_IAM___Access_Control_Paradigm_PlatformCapabilityIAM_v_1.0.1.pdf) -- [CX-0016 Company Attribute Verification](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0016-CompanyAttributeVerification-v.1.1.0.pdf) -- [CX-0017 Company Role by the Connector](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0017-CompanyRoleByTheConnector-v.1.1.0.pdf) -- [CX-0018 Eclipse Data Space Connector (EDC)](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0018-EclipseDataConnector_EDC_-v.2.0.1.pdf) -- [CX-0049 DID Document](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0049-DIDDocument-v.1.0.0.pdf) -- [CX-0050 Framework Agreement Credential](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0050-FrameworkAgreementCredential-v.1.0.0.pdf) -- [CX-0051 Summary Credential](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0051-SummaryCredential-v.1.0.0.pdf) +- [CX-0016 Company Attribute Verification](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0016-CompanyAttributeVerification-v1.1.0.pdf) +- [CX-0017 Company Role by the Connector](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0017-CompanyRoleByTheConnector-v1.1.0.pdf) +- [CX-0018 Eclipse Data Space Connector (EDC)](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0018-EclipseDataConnector_EDC_-v2.0.1.pdf) +- [CX-0049 DID Document](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0049-DIDDocument-v1.0.0.pdf) +- [CX-0050 Framework Agreement Credential](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0050-FrameworkAgreementCredential-v1.0.0.pdf) +- [CX-0051 Summary Credential](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0051-SummaryCredential-v1.0.0.pdf) To participate in the digital product passport use case, the following single standards **SHOULD** be fulfilled by data consumers / applications providers for which the standard is relevant: @@ -527,3 +527,7 @@ implementation that implements this standard. ### FIGURES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0098-AspectModelSecondaryMaterialContent/CX-0098-AspectModelSecondaryMaterialContent.md b/versioned_docs/version-24.03/standards/CX-0098-AspectModelSecondaryMaterialContent/CX-0098-AspectModelSecondaryMaterialContent.md index 774f906f8..05650663e 100644 --- a/versioned_docs/version-24.03/standards/CX-0098-AspectModelSecondaryMaterialContent/CX-0098-AspectModelSecondaryMaterialContent.md +++ b/versioned_docs/version-24.03/standards/CX-0098-AspectModelSecondaryMaterialContent/CX-0098-AspectModelSecondaryMaterialContent.md @@ -1,5 +1,5 @@ -# CX-0098 Aspect Model Secondary Material Content v.2.0.0 +# CX-0098 Aspect Model Secondary Material Content v2.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -209,3 +209,7 @@ file. ### FIGURES ### TABLES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0099-DataModelCertificateofDecommissioning/CX-0099-DataModelCertificateofDecommissioning.md b/versioned_docs/version-24.03/standards/CX-0099-DataModelCertificateofDecommissioning/CX-0099-DataModelCertificateofDecommissioning.md index 8536733be..8948fb318 100644 --- a/versioned_docs/version-24.03/standards/CX-0099-DataModelCertificateofDecommissioning/CX-0099-DataModelCertificateofDecommissioning.md +++ b/versioned_docs/version-24.03/standards/CX-0099-DataModelCertificateofDecommissioning/CX-0099-DataModelCertificateofDecommissioning.md @@ -188,3 +188,7 @@ an update will be provided. ### 3.2 NON-NORMATIVE REFERENCES - [SMT- How to create submodel template specification](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf) + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0100-TriangleForSecondaryMarketplace/CX-0100-TriangleForSecondaryMarketplace.md b/versioned_docs/version-24.03/standards/CX-0100-TriangleForSecondaryMarketplace/CX-0100-TriangleForSecondaryMarketplace.md index 891f55622..ec0a9e78c 100644 --- a/versioned_docs/version-24.03/standards/CX-0100-TriangleForSecondaryMarketplace/CX-0100-TriangleForSecondaryMarketplace.md +++ b/versioned_docs/version-24.03/standards/CX-0100-TriangleForSecondaryMarketplace/CX-0100-TriangleForSecondaryMarketplace.md @@ -183,3 +183,7 @@ No reference implementation at the moment. ### FIGURES ### TABLES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0102-Functional-Mock-Up/CX-0102-Functional-Mock-Up.md b/versioned_docs/version-24.03/standards/CX-0102-Functional-Mock-Up/CX-0102-Functional-Mock-Up.md index 053c8225d..131d5f554 100644 --- a/versioned_docs/version-24.03/standards/CX-0102-Functional-Mock-Up/CX-0102-Functional-Mock-Up.md +++ b/versioned_docs/version-24.03/standards/CX-0102-Functional-Mock-Up/CX-0102-Functional-Mock-Up.md @@ -1,4 +1,4 @@ -# CX-0102 Functional Mock Up v.1.0.0 +# CX-0102 Functional Mock Up v1.0.0 ## ABSTRACT @@ -33,7 +33,7 @@ The standard is relevant for modeling of physical assets. > *This section is non-normative* -CX - 0102 FUNCTIONAL-MOCK-UP v.1.0.0 +CX - 0102 FUNCTIONAL-MOCK-UP v1.0.0 The Functional Mock-up Interface (FMI) is a free standard that defines a container and an interface to exchange dynamic simulation models using a combination of XML files, binaries and C code, distributed as a ZIP file. It is supported by 170+ tools and maintained as a Modelica Association Project. The FMI implementation by a software modelling tool enables the creation of simulation models that can be interconnected. The file format of the FMI standard is called Functional Mock-up Unit (FMU) (source: https://fmi-standard.org/). In the context of Catena-X, simulation models can represent for example a component of a vehicle produced by a Tier-1. The Tier-1 develops the model of its component using any FMI compatible tool. The model is then exported as FMU. The model is now packed as a black box model. The person (for example from an OEM) who receives the simulation model can only see the input and output ports and the parameters and variables of the models that have been exposed by the model creator. In this way the intellectual properties of the model creator is protected. @@ -114,3 +114,7 @@ Not relevant ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0103-AspectModelDigitalProductPassport/CX-0103-AspectModelDigitalProductPassport.md b/versioned_docs/version-24.03/standards/CX-0103-AspectModelDigitalProductPassport/CX-0103-AspectModelDigitalProductPassport.md index 9ce9bf5bb..b7514abac 100644 --- a/versioned_docs/version-24.03/standards/CX-0103-AspectModelDigitalProductPassport/CX-0103-AspectModelDigitalProductPassport.md +++ b/versioned_docs/version-24.03/standards/CX-0103-AspectModelDigitalProductPassport/CX-0103-AspectModelDigitalProductPassport.md @@ -1,5 +1,5 @@ -# CX-0103 Digital Product Passport v.1.1.0 +# CX-0103 Digital Product Passport v1.1.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -211,3 +211,7 @@ A reference implementation of an application using or providing data conformant ### FIGURES ### TABLES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0104-AspectModelAssetTrackerLinks/CX-0104-AspectModelAssetTrackerLinks.md b/versioned_docs/version-24.03/standards/CX-0104-AspectModelAssetTrackerLinks/CX-0104-AspectModelAssetTrackerLinks.md index 7c3930fc7..8ae5057c7 100644 --- a/versioned_docs/version-24.03/standards/CX-0104-AspectModelAssetTrackerLinks/CX-0104-AspectModelAssetTrackerLinks.md +++ b/versioned_docs/version-24.03/standards/CX-0104-AspectModelAssetTrackerLinks/CX-0104-AspectModelAssetTrackerLinks.md @@ -1,4 +1,4 @@ -# CX - 0104 Aspect Model AssetTrackerLinks v.1.0.0 +# CX - 0104 Aspect Model AssetTrackerLinks v1.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -96,7 +96,7 @@ Asset and device are curently paired when set to true. Additional terminology used in this standard can be looked up in the glossary on the association homepage. -## 2 ASPECT MODEL “AssetTrackerLinks v.2.0.0” +## 2 ASPECT MODEL “AssetTrackerLinks v2.0.0” > *This section is normative* @@ -172,3 +172,7 @@ The data model follows the Standard [CX - 0045 Aspect Model Data Chain Template] ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0105-AssetTrackingTriangleDocument/CX-0105-AssetTrackingTriangleDocument.md b/versioned_docs/version-24.03/standards/CX-0105-AssetTrackingTriangleDocument/CX-0105-AssetTrackingTriangleDocument.md index ab43aa6ca..5cc875a84 100644 --- a/versioned_docs/version-24.03/standards/CX-0105-AssetTrackingTriangleDocument/CX-0105-AssetTrackingTriangleDocument.md +++ b/versioned_docs/version-24.03/standards/CX-0105-AssetTrackingTriangleDocument/CX-0105-AssetTrackingTriangleDocument.md @@ -153,19 +153,19 @@ Additional terminology used in this standard can be looked up in the glossary on To participate in the Asset Tracking use case, the following single standards MUST be fulfilled by all participants for which the standard is relevant: -CX-0002 Digital Twins in Catena-X v.2.0.0 +CX-0002 Digital Twins in Catena-X v2.0.0 -CX-0018 Eclipse Data Space Connector (EDC) v.2.1.0 +CX-0018 Eclipse Data Space Connector (EDC) v2.1.0 -CX-0045 Aspect Model Data Chain Template v.1.1.1 +CX-0045 Aspect Model Data Chain Template v1.1.1 -CX-0083 Aspect Model IoTSensorDeviceDefinition v.1.0.0 +CX-0083 Aspect Model IoTSensorDeviceDefinition v1.0.0 -CX-0106 Aspect Model IoTSensorData v.1.0.0 +CX-0106 Aspect Model IoTSensorData v1.0.0 -CX-0104 Aspect Model AssetTrackerLinks v.1.0.0 +CX-0104 Aspect Model AssetTrackerLinks v1.0.0 -CX-0070 Asset Tracking Platform API Standardization v.1.0.0 +CX-0070 Asset Tracking Platform API Standardization v1.0.0 #### 2.1.2 DATA REQUIRED @@ -240,7 +240,7 @@ ex: > *This section is normative* -### 3.1 ASPECT MODEL "IotSensorDeviceDefinition v.2.0.0" +### 3.1 ASPECT MODEL "IotSensorDeviceDefinition v2.0.0" #### 3.1.1 INTRODUCTION @@ -288,7 +288,7 @@ https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.io A AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification conformant to \[[SMT](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf)]. -### 3.2 ASPECT MODEL "IotSensorData v.2.0.0" +### 3.2 ASPECT MODEL "IotSensorData v2.0.0" #### 3.2.1 INTRODUCTION @@ -343,7 +343,7 @@ https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.io A AASX file can be generated from the RDF Turtle file. The AASX file defines one of the requested artifacts for a Submodel Template Specification conformant to \[[SMT](https://industrialdigitaltwin.org/wp-content/uploads/2022/12/I40-IDTA-WS-Process-How-to-write-a-SMT-FINAL-.pdf)]. -### 3.3 ASPECT MODEL "AssetTrackerLinks v.2.0.0" +### 3.3 ASPECT MODEL "AssetTrackerLinks v2.0.0" #### 3.3.1 INTRODUCTION @@ -510,19 +510,19 @@ In case of an error, one of the following responses can occur: > *This section is normative* -CX-0002 Digital Twins in Catena-X v.2.0.0 +CX-0002 Digital Twins in Catena-X v2.0.0 -CX-0018 Eclipse Data Space Connector (EDC) v.2.1.0 +CX-0018 Eclipse Data Space Connector (EDC) v2.1.0 -CX-0045 Aspect Model Data Chain Template v.1.1.1 +CX-0045 Aspect Model Data Chain Template v1.1.1 -CX-0083 Aspect Model IoTSensorDeviceDefinition v.1.0.0 +CX-0083 Aspect Model IoTSensorDeviceDefinition v1.0.0 -CX-0106 Aspect Model IoTSensorData v.1.0.0 +CX-0106 Aspect Model IoTSensorData v1.0.0 -CX-0104 Aspect Model AssetTrackerLinks v.1.0.0 +CX-0104 Aspect Model AssetTrackerLinks v1.0.0 -CX-0070 Asset Tracking Platform API Standardization v.1.0.0 +CX-0070 Asset Tracking Platform API Standardization v1.0.0 ### 5.2 NON-NORMATIVE REFERENCES @@ -553,3 +553,7 @@ CX-0070 Asset Tracking Platform API Standardization v.1.0.0 ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0106-AspectModelIoTSensorData/CX-0106-AspectModelIoTSensorData-1.0.0.md b/versioned_docs/version-24.03/standards/CX-0106-AspectModelIoTSensorData/CX-0106-AspectModelIoTSensorData.md similarity index 97% rename from versioned_docs/version-24.03/standards/CX-0106-AspectModelIoTSensorData/CX-0106-AspectModelIoTSensorData-1.0.0.md rename to versioned_docs/version-24.03/standards/CX-0106-AspectModelIoTSensorData/CX-0106-AspectModelIoTSensorData.md index d6624e340..6c2d4ed07 100644 --- a/versioned_docs/version-24.03/standards/CX-0106-AspectModelIoTSensorData/CX-0106-AspectModelIoTSensorData-1.0.0.md +++ b/versioned_docs/version-24.03/standards/CX-0106-AspectModelIoTSensorData/CX-0106-AspectModelIoTSensorData.md @@ -1,4 +1,4 @@ -# CX - 0106 Aspect Model IotSensorData v.1.0.0 +# CX-0106 Aspect Model IotSensorData v1.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -135,7 +135,7 @@ The method under which the sensing data is transmitted from the source to the re Additional terminology used in this standard can be looked up in the glossary on the association homepage. -## 2 ASPECT MODEL "IotSensorData v.2.0.0" +## 2 ASPECT MODEL "IotSensorData v2.0.0" > *This section is normative* @@ -220,3 +220,7 @@ https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main/io.catenax.io ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0107-AspectModelReuseCertificate/CX-0107-AspectModelReuseCertificate.md b/versioned_docs/version-24.03/standards/CX-0107-AspectModelReuseCertificate/CX-0107-AspectModelReuseCertificate.md index 26da34f65..e8ae00929 100644 --- a/versioned_docs/version-24.03/standards/CX-0107-AspectModelReuseCertificate/CX-0107-AspectModelReuseCertificate.md +++ b/versioned_docs/version-24.03/standards/CX-0107-AspectModelReuseCertificate/CX-0107-AspectModelReuseCertificate.md @@ -1,4 +1,4 @@ -# CX-0107-AspectModelReuseCertificate v.1.0.0 +# CX-0107-AspectModelReuseCertificate v1.0.0 ## ABSTRACT @@ -150,3 +150,7 @@ GER: [End-of-life vehicle regulation - AltfahrzeugV](https://www.gesetze-im-inte ### ANNEXES N/A + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0108-AspectModelWasteCertificate/CX-0108-AspectModelWasteCertificate.md b/versioned_docs/version-24.03/standards/CX-0108-AspectModelWasteCertificate/CX-0108-AspectModelWasteCertificate.md index 7b6473e37..464807c23 100644 --- a/versioned_docs/version-24.03/standards/CX-0108-AspectModelWasteCertificate/CX-0108-AspectModelWasteCertificate.md +++ b/versioned_docs/version-24.03/standards/CX-0108-AspectModelWasteCertificate/CX-0108-AspectModelWasteCertificate.md @@ -1,4 +1,4 @@ -# CX - 0108 Waste Certificate v.1.0.0 +# CX - 0108 Waste Certificate v1.0.0 ## ABSTRACT @@ -152,3 +152,7 @@ GER: [End-of-life vehicle regulation - AltfahrzeugV](https://www.gesetze-im-inte ### ANNEXES N/A + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0109-AspectModelRefrubishingCertificate/CX-0109-AspectModelRefrubishingCertificate.md b/versioned_docs/version-24.03/standards/CX-0109-AspectModelRefrubishingCertificate/CX-0109-AspectModelRefrubishingCertificate.md index 436f93b1e..ca7cb814a 100644 --- a/versioned_docs/version-24.03/standards/CX-0109-AspectModelRefrubishingCertificate/CX-0109-AspectModelRefrubishingCertificate.md +++ b/versioned_docs/version-24.03/standards/CX-0109-AspectModelRefrubishingCertificate/CX-0109-AspectModelRefrubishingCertificate.md @@ -1,4 +1,4 @@ -# CX-0109 Aspect Model Refurbishing Certificate v.1.0.0 +# CX-0109 Aspect Model Refurbishing Certificate v1.0.0 ## ABSTRACT @@ -150,3 +150,7 @@ GER: [End-of-life vehicle regulation - AltfahrzeugV](https://www.gesetze-im-inte ### ANNEXES N/A + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0111-AspectModelRemanufacturingCertificate/CX-0111-AspectModelRemanufacturingCertificate.md b/versioned_docs/version-24.03/standards/CX-0111-AspectModelRemanufacturingCertificate/CX-0111-AspectModelRemanufacturingCertificate.md index 33b03b115..b200ab80d 100644 --- a/versioned_docs/version-24.03/standards/CX-0111-AspectModelRemanufacturingCertificate/CX-0111-AspectModelRemanufacturingCertificate.md +++ b/versioned_docs/version-24.03/standards/CX-0111-AspectModelRemanufacturingCertificate/CX-0111-AspectModelRemanufacturingCertificate.md @@ -1,4 +1,4 @@ -# CX-0111-AspectModelRemanufacturingCertificate-1.0.0 +# CX-0111 - Aspect Model RemanufacturingCertificate v1.0.0 ## ABSTRACT @@ -147,3 +147,7 @@ GER: [End-of-life vehicle regulation - AltfahrzeugV](https://www.gesetze-im-inte ### ANNEXES N/A + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0112-AspectModelMaterialRecyclingCertificate/CX-0112-AspectModelMaterialRecyclingCertificate.md b/versioned_docs/version-24.03/standards/CX-0112-AspectModelMaterialRecyclingCertificate/CX-0112-AspectModelMaterialRecyclingCertificate.md index 2c2f81b26..950a14442 100644 --- a/versioned_docs/version-24.03/standards/CX-0112-AspectModelMaterialRecyclingCertificate/CX-0112-AspectModelMaterialRecyclingCertificate.md +++ b/versioned_docs/version-24.03/standards/CX-0112-AspectModelMaterialRecyclingCertificate/CX-0112-AspectModelMaterialRecyclingCertificate.md @@ -1,4 +1,4 @@ -# CX-0112-AspectModelMaterialRecyclingCertificate-v1.0.0.md +# CX-0112 - Aspect Model MaterialRecyclingCertificate v1.0.0 ## ABSTRACT @@ -149,3 +149,7 @@ GER: [End-of-life vehicle regulation - AltfahrzeugV](https://www.gesetze-im-inte ### ANNEXES N/A + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0113-AspectModelESSDatamodel/CX-0113-AspectModelESSDatamodel.md b/versioned_docs/version-24.03/standards/CX-0113-AspectModelESSDatamodel/CX-0113-AspectModelESSDatamodel.md index 918e48ca3..1425807b8 100644 --- a/versioned_docs/version-24.03/standards/CX-0113-AspectModelESSDatamodel/CX-0113-AspectModelESSDatamodel.md +++ b/versioned_docs/version-24.03/standards/CX-0113-AspectModelESSDatamodel/CX-0113-AspectModelESSDatamodel.md @@ -1,5 +1,5 @@ -# CX-0113 Aspect Model ESS Incident Data Model v.1.0.0 +# CX-0113 Aspect Model ESS Incident Data Model v1.0.0 ## FOR WHOM IS THE STANDARD DESIGNED @@ -300,3 +300,7 @@ file. ### FIGURES ### TABLES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0116-SanctionWatchlistDashboard/CX-0116-SanctionWatchlistDashboard.md b/versioned_docs/version-24.03/standards/CX-0116-SanctionWatchlistDashboard/CX-0116-SanctionWatchlistDashboard.md index 60e3e7122..738445234 100644 --- a/versioned_docs/version-24.03/standards/CX-0116-SanctionWatchlistDashboard/CX-0116-SanctionWatchlistDashboard.md +++ b/versioned_docs/version-24.03/standards/CX-0116-SanctionWatchlistDashboard/CX-0116-SanctionWatchlistDashboard.md @@ -4,7 +4,7 @@ Doing business with companies (and affiliates) which are sanctioned or affected by embargos can result in fines and reputational damage. However, identification of sanctioned partners is difficult due to the vast amount of different sanction lists from several countries and authorities. Even manual checks are difficult due to a lack of high-quality data provisioned by the authorities. With Sanction and Watchlist Monitoring, data synchronized with a data mirror is monitored continuously against the latest sanction and watch lists. The Sanction Party Watchlist Dashboard (SWD) has to provide a summary on potential matches. The matching against sanction and watch lists have to be activated in the company data lookup, so data maintainers are already notified during creation or update workflows. The monitoring scope has to be extended to political exposed persons (so called PEPs). SWD has to visualize the outcome of the sanction watchlist monitoring rules via a dashboard. -SWD has to use the Gate API CX-0074\_V.1.1.0 or higher for pulling BP data records. SWD has to be a client/ server cloud application which contains a Web Client and a Cloud Server Application. +SWD has to use the Gate API CX-0074\_v1.1.0 or higher for pulling BP data records. SWD has to be a client/ server cloud application which contains a Web Client and a Cloud Server Application. SWD has to contain a user and authorization management capability aligned with the CX Portal and Marketplace user management. SWD has to contain an API and has to be available in English and German language ## 1 INTRODUCTION @@ -300,3 +300,7 @@ Intentionally left blank. [^1]: https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf [^2]: https://catena-x.net/de/standardisierung/catena-x-einfuehren-umsetzen/standardisierung/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0118-ActualDeliveryInformationExchange/CX-0118-ActualDeliveryInformationExchange.md b/versioned_docs/version-24.03/standards/CX-0118-ActualDeliveryInformationExchange/CX-0118-ActualDeliveryInformationExchange.md index 7d5f3d4e1..61838afd4 100644 --- a/versioned_docs/version-24.03/standards/CX-0118-ActualDeliveryInformationExchange/CX-0118-ActualDeliveryInformationExchange.md +++ b/versioned_docs/version-24.03/standards/CX-0118-ActualDeliveryInformationExchange/CX-0118-ActualDeliveryInformationExchange.md @@ -1350,3 +1350,7 @@ There **MUST** be arrival information, to give the supplier more transparency. > *This section is non-normative* Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0120-ShortTermMaterialDemandExchange/CX-0120-ShortTermMaterialDemandExchange.md b/versioned_docs/version-24.03/standards/CX-0120-ShortTermMaterialDemandExchange/CX-0120-ShortTermMaterialDemandExchange.md index b286a602b..497f65795 100644 --- a/versioned_docs/version-24.03/standards/CX-0120-ShortTermMaterialDemandExchange/CX-0120-ShortTermMaterialDemandExchange.md +++ b/versioned_docs/version-24.03/standards/CX-0120-ShortTermMaterialDemandExchange/CX-0120-ShortTermMaterialDemandExchange.md @@ -1150,3 +1150,7 @@ and Day 2 to build up a safety stock. > *This section is non-normative* Not applicable + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0121-PlannedProductionOutputExchange/CX-0121-PlannedProductionOutputExchange.md b/versioned_docs/version-24.03/standards/CX-0121-PlannedProductionOutputExchange/CX-0121-PlannedProductionOutputExchange.md index 93be8b68c..fae06090f 100644 --- a/versioned_docs/version-24.03/standards/CX-0121-PlannedProductionOutputExchange/CX-0121-PlannedProductionOutputExchange.md +++ b/versioned_docs/version-24.03/standards/CX-0121-PlannedProductionOutputExchange/CX-0121-PlannedProductionOutputExchange.md @@ -1132,3 +1132,7 @@ In any case, the supplier must ensure that the information is consistent and pla > *This section is non-normative* Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0122-ItemStockExchange/CX-0122-ItemStockExchange.md b/versioned_docs/version-24.03/standards/CX-0122-ItemStockExchange/CX-0122-ItemStockExchange.md index b9c356111..a815d59de 100644 --- a/versioned_docs/version-24.03/standards/CX-0122-ItemStockExchange/CX-0122-ItemStockExchange.md +++ b/versioned_docs/version-24.03/standards/CX-0122-ItemStockExchange/CX-0122-ItemStockExchange.md @@ -21,8 +21,8 @@ for facilitating such an exchange. This is the first version of the CX-0122 standard. The CX-0122 standard **obsoletes** the following Catena-X standards: -- CX-0085 ProductStock Aspect Model v.1.0.0 -- CX-0086 Product Stock Exchange API v.1.0.0 +- CX-0085 ProductStock Aspect Model v1.0.0 +- CX-0086 Product Stock Exchange API v1.0.0 ## 1 INTRODUCTION @@ -1223,3 +1223,7 @@ respective location with its address. > *This section is non-normative* Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0123-QualityUseCaseStandard/CX-0123-QualityUseCaseStandard.md b/versioned_docs/version-24.03/standards/CX-0123-QualityUseCaseStandard/CX-0123-QualityUseCaseStandard.md index d97a53c9b..d9140f047 100644 --- a/versioned_docs/version-24.03/standards/CX-0123-QualityUseCaseStandard/CX-0123-QualityUseCaseStandard.md +++ b/versioned_docs/version-24.03/standards/CX-0123-QualityUseCaseStandard/CX-0123-QualityUseCaseStandard.md @@ -1,5 +1,5 @@ -# CX-0123 Quality Use Case Standard v.1.0.0 +# CX-0123 Quality Use Case Standard v1.0.0 ## ABSTRACT @@ -65,23 +65,23 @@ The so generated files are transferred between different Catena-X participants u In order to participate in the Catena-X use case "Quality" the following single standards **MUST** be fulfilled by all participants: -CX - 0018 Eclipse Data Connector (EDC) v.2.1.0 +CX - 0018 Eclipse Data Connector (EDC) v2.1.0 As OEM data provider I **MUST** align to the following aspect models in the corresponding data exchange: -Aspect Model QualityTask v.1.0.0 -Aspect Model VehicleProductDescription v.3.0.0 -Aspect Model FleetDiagnosticData v.1.0.0 -Aspect Model FleetClaimData v.1.0.0 -Aspect Model FleetVehicles v.1.0.0 -Aspect Model QualityTaskAttachment v.1.0.0 +Aspect Model QualityTask v1.0.0 +Aspect Model VehicleProductDescription v3.0.0 +Aspect Model FleetDiagnosticData v1.0.0 +Aspect Model FleetClaimData v1.0.0 +Aspect Model FleetVehicles v1.0.0 +Aspect Model QualityTaskAttachment v1.0.0 As Supplier data provider I **MUST** align to the following aspect models in the corresponding data exchange: -Aspect Model QualityTask v.1.0.0 -Aspect Model PartAnalyses v.2.0.0 -Aspect Model ManufacturedPartsQualityInformation v.1.0.0 -Aspect Model QualityTaskAttachment v.1.0.0 +Aspect Model QualityTask v1.0.0 +Aspect Model PartAnalyses v2.0.0 +Aspect Model ManufacturedPartsQualityInformation v1.0.0 +Aspect Model QualityTaskAttachment v1.0.0 - Data provisioning and consuming **MUST** be done according the standardized semantic data models. - The data provider defines the data content that will be provided. Provided data assets are defined in data sharing agreements and/or data usage policies. @@ -524,7 +524,7 @@ This semantic model has the unique identifier: urn:samm:io.catenax.fleet.vehicles:1.0.0 -This model has an external reference to Aspect Model Vehicle Product Description v.3.0.0 with unique identifier urn:samm:io.catenax.vehicle.product_description:3.0.0 +This model has an external reference to Aspect Model Vehicle Product Description v3.0.0 with unique identifier urn:samm:io.catenax.vehicle.product_description:3.0.0 #### 3.7.5 FORMATS OF SEMANTIC MODEL @@ -643,7 +643,7 @@ not applicable > *This section is normative* ```text - CX - 0018 EclipseDataConnector (EDC) v.2.1.0 + CX - 0018 EclipseDataConnector (EDC) v2.1.0 ``` ### 6.2 NON-NORMATIVE REFERENCES @@ -655,3 +655,7 @@ not applicable ### FIGURES ### TABLES + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0125-TraceabilityUseCase/CX-0125-TraceabilityUseCase.md b/versioned_docs/version-24.03/standards/CX-0125-TraceabilityUseCase/CX-0125-TraceabilityUseCase.md index 9013171c0..b992e8e58 100644 --- a/versioned_docs/version-24.03/standards/CX-0125-TraceabilityUseCase/CX-0125-TraceabilityUseCase.md +++ b/versioned_docs/version-24.03/standards/CX-0125-TraceabilityUseCase/CX-0125-TraceabilityUseCase.md @@ -1,4 +1,4 @@ -# CX-0125 Traceability Use Case v.1.0.0 +# CX-0125 Traceability Use Case v1.0.0 ## ABSTRACT @@ -765,7 +765,7 @@ The semantic model has the unique identifier The rdf turtle file, an instance of the Semantic Aspect Meta Model, is the master for generating additional file formats and serializations. -TractionBatteryCode **v.1.0.0** (optional) +TractionBatteryCode **v1.0.0** (optional) https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.traction_battery_code/1.0.0/TractionBatteryCode.ttl @@ -1232,3 +1232,7 @@ Below, the UML sequence diagram to update a quality alert is depicted. ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0126-IndustryCorePartType/CX-0126-IndustryCorePartType.md b/versioned_docs/version-24.03/standards/CX-0126-IndustryCorePartType/CX-0126-IndustryCorePartType.md index 38f9911c1..4db6ef90b 100644 --- a/versioned_docs/version-24.03/standards/CX-0126-IndustryCorePartType/CX-0126-IndustryCorePartType.md +++ b/versioned_docs/version-24.03/standards/CX-0126-IndustryCorePartType/CX-0126-IndustryCorePartType.md @@ -473,3 +473,7 @@ This section is empty. > *This section is non-normative* This section is empty. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0127-IndustryCorePartInstance/CX-0127-IndustryCorePartInstance.md b/versioned_docs/version-24.03/standards/CX-0127-IndustryCorePartInstance/CX-0127-IndustryCorePartInstance.md index ae8b941d7..c5feeeea3 100644 --- a/versioned_docs/version-24.03/standards/CX-0127-IndustryCorePartInstance/CX-0127-IndustryCorePartInstance.md +++ b/versioned_docs/version-24.03/standards/CX-0127-IndustryCorePartInstance/CX-0127-IndustryCorePartInstance.md @@ -901,3 +901,7 @@ This section is empty. > *This section is non-normative* This section is empty. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0128-DemandandCapacityManagementDataExchange/CX-0128-DemandandCapacityManagementDataExchange.md b/versioned_docs/version-24.03/standards/CX-0128-DemandandCapacityManagementDataExchange/CX-0128-DemandandCapacityManagementDataExchange.md index de401c8f3..df5bde21d 100644 --- a/versioned_docs/version-24.03/standards/CX-0128-DemandandCapacityManagementDataExchange/CX-0128-DemandandCapacityManagementDataExchange.md +++ b/versioned_docs/version-24.03/standards/CX-0128-DemandandCapacityManagementDataExchange/CX-0128-DemandandCapacityManagementDataExchange.md @@ -2150,3 +2150,7 @@ Unit of Measure typically used in DCM context. | Zyklus | B7 | cycle | Zyklus | [empty] | cyl | unit:cycle | *Table 1: Units of measurement used in DCM* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0129-RequestforQuotationExchange/CX-0129-RequestforQuotationExchange.md b/versioned_docs/version-24.03/standards/CX-0129-RequestforQuotationExchange/CX-0129-RequestforQuotationExchange.md index bdb0d6869..984f7ad9d 100644 --- a/versioned_docs/version-24.03/standards/CX-0129-RequestforQuotationExchange/CX-0129-RequestforQuotationExchange.md +++ b/versioned_docs/version-24.03/standards/CX-0129-RequestforQuotationExchange/CX-0129-RequestforQuotationExchange.md @@ -1,4 +1,4 @@ -# CX - 0129 Request for Quotation Exchange v.1.0.0 +# CX-0129 Request for Quotation Exchange v1.0.0 ## ABSTRACT @@ -510,3 +510,7 @@ Not applicable. > *This section is non-normative* Not applicable. + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0131-CircularityTriangle/CX-0131-CircularityTriangle.md b/versioned_docs/version-24.03/standards/CX-0131-CircularityTriangle/CX-0131-CircularityTriangle.md index 487739f79..ceb1387d0 100644 --- a/versioned_docs/version-24.03/standards/CX-0131-CircularityTriangle/CX-0131-CircularityTriangle.md +++ b/versioned_docs/version-24.03/standards/CX-0131-CircularityTriangle/CX-0131-CircularityTriangle.md @@ -1,4 +1,4 @@ -# CX-0131 Circularity Triangle v.1.0.0 +# CX-0131 Circularity Triangle v1.0.0 ## ABSTRACT @@ -162,17 +162,17 @@ The contract definition **MUST** follow the CX-Standard [0018](#21-overall-stand To participate in the EoL/Dismantling Services use-case, the following single standards are **RECOMMENDED** to be fulfilled by all participants for which the standard is relevant: - [CX-0019-AspectModelSerialPart v2.0.0](https://catena-x.net/de/standard-library) -- [CX-0020 AspectModelSingleLevelBoMAsBuilt v.2.0.0](https://catena-x.net/de/standard-library) -- [CX-0030-Data Model BoMAsSpecified v.2.0.0](https://catena-x.net/de/standard-library) -- [CX-0031 Data Model MaterialForHomologation v.1.0.1](https://catena-x.net/de/standard-library) -- [CX-0032 Data Model PartAsSpecified v.1.0.1](https://catena-x.net/de/standard-library) -- [CX-0037 Aspect Model: VehicleProductDescription v.2.0.0](https://catena-x.net/de/standard-library) +- [CX-0020 AspectModelSingleLevelBoMAsBuilt v2.0.0](https://catena-x.net/de/standard-library) +- [CX-0030-Data Model BoMAsSpecified v2.0.0](https://catena-x.net/de/standard-library) +- [CX-0031 Data Model MaterialForHomologation v1.0.1](https://catena-x.net/de/standard-library) +- [CX-0032 Data Model PartAsSpecified v1.0.1](https://catena-x.net/de/standard-library) +- [CX-0037 Aspect Model: VehicleProductDescription v2.0.0](https://catena-x.net/de/standard-library) - [CX-0036 Aspect Model: QualityTask v1.0.1](https://catena-x.net/de/standard-library) - [CX-0038 Aspect Model: Fleet.DiagnosticData v1.0.1](https://catena-x.net/de/standard-library) - [CX-0039 Aspect Model: Fleet.ClaimData v1.0.1](https://catena-x.net/de/standard-library) - [CX-0040-Aspect Model: PartAnalyses v2.0.0](https://catena-x.net/de/standard-library) - [CX-0041-Aspect Model: ManufacturedPartsQualityInformation v1.0.1](https://catena-x.net/de/standard-library) -- [CX-0066 Aspect Model: EndofLifeofVehicleCompliance v.1.0.0](https://catena-x.net/de/standard-library) +- [CX-0066 Aspect Model: EndofLifeofVehicleCompliance v1.0.0](https://catena-x.net/de/standard-library) - [CX-0091 Aspect Model: Fleet.Vehicles v1.0.0](https://catena-x.net/de/standard-library) - [CX-0092 Aspect Model: QualityTaskAttachment v1.0.0](https://catena-x.net/de/standard-library) @@ -279,22 +279,22 @@ For the sub use case EoL/Dismantling Services the condition mentioned under [2.6 To participate in the CE-Assistant use-case, the following single standards are **RECOMMENDED** to be fulfilled by all participants for which the standard is relevant: -- [CX-0020-Aspect Model: SingleLevelBoMAsBuilt v.2.0.0](https://catena-x.net/de/standard-library) -- [CX-0021-Aspect Model: Batch v.1.0.1](https://catena-x.net/de/standard-library) -- [CX-0026-Product Carbon Footprint Data Model v.1.2.0](https://catena-x.net/de/standard-library) -- [CX-0027-Product Carbon Footprint Aspect Model v.1.0.0](https://catena-x.net/de/standard-library) -- [CX-0028-Product Carbon Footprint Request API v.1.1.2](https://catena-x.net/de/standard-library) -- [CX-0029-Product Carbon Footprint Rulebook v.2.0.0](https://catena-x.net/de/standard-library) -- [CX-0030-Data Model BoMAsSpecified v.1.0.1](https://catena-x.net/de/standard-library) -- [CX-0031-Data Model MaterialforHomologation v.1.0.1](https://catena-x.net/de/standard-library) +- [CX-0020-Aspect Model: SingleLevelBoMAsBuilt v2.0.0](https://catena-x.net/de/standard-library) +- [CX-0021-Aspect Model: Batch v1.0.1](https://catena-x.net/de/standard-library) +- [CX-0026-Product Carbon Footprint Data Model v1.2.0](https://catena-x.net/de/standard-library) +- [CX-0027-Product Carbon Footprint Aspect Model v1.0.0](https://catena-x.net/de/standard-library) +- [CX-0028-Product Carbon Footprint Request API v1.1.2](https://catena-x.net/de/standard-library) +- [CX-0029-Product Carbon Footprint Rulebook v2.0.0](https://catena-x.net/de/standard-library) +- [CX-0030-Data Model BoMAsSpecified v1.0.1](https://catena-x.net/de/standard-library) +- [CX-0031-Data Model MaterialforHomologation v1.0.1](https://catena-x.net/de/standard-library) - [CX-0032-Data Model PartAsSpecified v. 1.0.1](https://catena-x.net/de/standard-library) -- [CX-0033-Data Model Return Request v.1.0.1](https://catena-x.net/de/standard-library) -- [CX-0034-Data Model Battery Pass v.1.0.1](https://catena-x.net/de/standard-library) -- [CX-0035-Data Model Marketplaceoffer v.1.0.0](https://catena-x.net/de/standard-library) -- [CX-0037-Semantic Model Vehicle Product Discription v.2.0.0](https://catena-x.net/de/standard-library) -- [CX-0040 Parts Analyses v.2.0.0](https://catena-x.net/de/standard-library) -- [CX-0041 Manufactured Parts Quality Information v.1.0.1](https://catena-x.net/de/standard-library) -- [CX-0057 Semantic Model: RemainingUsefulLife v.1.0.0](https://catena-x.net/de/standard-library) +- [CX-0033-Data Model Return Request v1.0.1](https://catena-x.net/de/standard-library) +- [CX-0034-Data Model Battery Pass v1.0.1](https://catena-x.net/de/standard-library) +- [CX-0035-Data Model Marketplaceoffer v1.0.0](https://catena-x.net/de/standard-library) +- [CX-0037-Semantic Model Vehicle Product Discription v2.0.0](https://catena-x.net/de/standard-library) +- [CX-0040 Parts Analyses v2.0.0](https://catena-x.net/de/standard-library) +- [CX-0041 Manufactured Parts Quality Information v1.0.1](https://catena-x.net/de/standard-library) +- [CX-0057 Semantic Model: RemainingUsefulLife v1.0.0](https://catena-x.net/de/standard-library) - [CX-0091 Aspect Model: Fleet Vehicles 1.0.0](https://catena-x.net/de/standard-library) #### 2.5.2 DATA REQUIRED for CE Assistant @@ -425,3 +425,7 @@ To understand the standard, the following use case related papers can be helpful > *This section is non-normative* N/A + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0133-OnlineControlandSimulation/CX-0133-OnlineControlandSimulation.md b/versioned_docs/version-24.03/standards/CX-0133-OnlineControlandSimulation/CX-0133-OnlineControlandSimulation.md index 3b41c3b4b..446793603 100644 --- a/versioned_docs/version-24.03/standards/CX-0133-OnlineControlandSimulation/CX-0133-OnlineControlandSimulation.md +++ b/versioned_docs/version-24.03/standards/CX-0133-OnlineControlandSimulation/CX-0133-OnlineControlandSimulation.md @@ -1,4 +1,4 @@ -# CX-0133 Online Control and Simulation 1.0.0 +# CX-0133 Online Control and Simulation v1.0.0 ## ABSTRACT @@ -1602,3 +1602,7 @@ n.a. ## REVISIONS & UPDATE ## COPYRIGHT & TRADEMARKS + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0134-ProductCarbonFootprintCalculationIntegration/CX-0134-ProductCarbonFootprintCalculationIntegration.md b/versioned_docs/version-24.03/standards/CX-0134-ProductCarbonFootprintCalculationIntegration/CX-0134-ProductCarbonFootprintCalculationIntegration.md index 8b67ddee8..5c5cc8f98 100644 --- a/versioned_docs/version-24.03/standards/CX-0134-ProductCarbonFootprintCalculationIntegration/CX-0134-ProductCarbonFootprintCalculationIntegration.md +++ b/versioned_docs/version-24.03/standards/CX-0134-ProductCarbonFootprintCalculationIntegration/CX-0134-ProductCarbonFootprintCalculationIntegration.md @@ -1,5 +1,5 @@ -# CX-0134 Product Carbon Footprint Calculation Integration v.1.0.0 +# CX-0134 Product Carbon Footprint Calculation Integration v1.0.0 ## ABSTRACT @@ -192,3 +192,7 @@ To prove conformity with the PCF calculation integration standard, the following ### TABLES > *This section is non-normative* + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright). diff --git a/versioned_docs/version-24.03/standards/CX-0135-CompanyCertificateManagement/CX-0135-CompanyCertificateManagement.md b/versioned_docs/version-24.03/standards/CX-0135-CompanyCertificateManagement/CX-0135-CompanyCertificateManagement.md index 6a137ce1f..b2294ae5c 100644 --- a/versioned_docs/version-24.03/standards/CX-0135-CompanyCertificateManagement/CX-0135-CompanyCertificateManagement.md +++ b/versioned_docs/version-24.03/standards/CX-0135-CompanyCertificateManagement/CX-0135-CompanyCertificateManagement.md @@ -1,4 +1,4 @@ -# CX-0135 - BP company certificate management v.1.0.0 +# CX-0135 BP company certificate management v1.0.0 ## ABSTRACT @@ -67,7 +67,7 @@ A company has 100 customers, that provide different certificates, from different In this section the different parts of the data model are explained. The data model is implemented according to the API specification that is published in the Tractus-X open source repository: -[BPDM certificate management api](https://github.com/eclipse-tractusx/bpdm-certificate-management/tree/main/doc/api)(V.1.0.0) +[BPDM certificate management api](https://github.com/eclipse-tractusx/bpdm-certificate-management/tree/main/doc/api)(v1.0.0) #### 1.5.1 BPNL BUSINESS PARTNER NUMBER LEGAL ENTITY @@ -275,3 +275,7 @@ Intentionally left blank. [^4] : https://catena-x.net/fileadmin/user_upload/Vereinsdokumente/Catena-X_IP_Regelwerk_IP_Regulations.pdf [^5] : https://catena-x.net/de/standardisierung/catena-x-einfuehren-umsetzen/standardisierung/standard-library + +## Legal + +Copyright © 2024 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit [here](/copyright).