Skip to main content
Version: 24.12

Data Provider

Traceability kit banner

The following page offers specific developer resources, including payloads and API endpoints for data providers. It is important to read the business and architecture view first to understand everything.

Aspect Models​

Aspect models are mostly easy to create by transforming a company's internal data into the target aspect model. Transformations are mostly straightforward in these cases. If necessary, special steps in creating aspect models are mentioned in the corresponding sections.

The following section shows an overview of all aspect models that are currently attached to part type or part instance twins by Catena-X use cases.

Digital Twin TypeAspect ModelMandatory VersionOptional VersionsKITStandard
PartTypePartTypeInformation1.0.0Industry CoreCX-0126 Industry Core: Part Type v2.0.0
SingleLevelBomAsPlanned3.0.0Industry CoreCX-0126 Industry Core: Part Type v2.0.0
SingleLevelUsageAsPlanned2.0.0Industry CoreCX-0126 Industry Core: Part Type v2.0.0
PartInstanceSerialPart3.0.0Industry CoreCX-0127 Industry Core: Part Instance v2.0.0
Batch3.0.0Industry CoreCX-0127 Industry Core: Part Instance v2.0.0
JustInSequencePart3.0.0Industry CoreCX-0127 Industry Core: Part Instance v2.0.0
SingleLevelBomAsBuilt3.0.0Industry CoreCX-0127 Industry Core: Part Instance v2.0.0
SingleLevelUsageAsBuilt3.0.0Industry CoreCX-0127 Industry Core: Part Instance v2.0.0

The following section shows an overview of all aspect models of the Traceability Use Case that can be attached to part instance twins.

Digital Twin TypeAspect ModelMandatory VersionOptional VersionsKITStandard
PartInstanceTractionBatteryCode2.0.0TraceabilityCX-0125 Traceability Use Case v2.0.0
SoftwareInformation1.0.0TraceabilityN/A
CertificateSigningRequests1.0.0TraceabilityN/A
SpecialCharacteristics1.0.0TraceabilityN/A

TractionBatteryCode​

The aspect provides the information of the Traction battery code of a battery cell, a battery module or a battery pack according to the chinese standard GB/T 34014-2017. Furthermore, it provides the traction battery codes for the assembled sub parts of the component, e.g. Traction battery code of a battery module plus all the traction battery codes of the assembled battery cells of this battery module.

Aspect model in GitHub:

Example: Submodel TractionBatteryCode for a Battery Cell​
{
  "productType": "cell",
  "tractionBatteryCode": "X12CCPM27KLPCLE662382320"
}
Example: Submodel TractionBatteryCode for a Battery Module​
{
  "productType": "module",
  "tractionBatteryCode": "B54MCPM27KLPCLE6A7519857",
  "subcomponents": [
    {
      "productType": "cell",
      "tractionBatteryCode": "X12CCPM27KLPCLE662382320"
    },
    {
      "productType": "cell",
      "tractionBatteryCode": "X12CCPM27KLPCLE662382321"
    }
  ]
}
Example: Submodel TractionBatteryCode for a Battery Pack​
{
  "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"
        }
      ]
    }
  ]
}

SoftwareInformation​

The software information aspect model contains the essential information of all software components that have been implemented or flashed in an instantiated part (e.g. serialized part).

Aspect model in GitHub:

Example: Submodel SoftwareInformation​
{
  "catenaXId": "urn:uuid:454ffa8e-f88d-4ad1-be45-06981756aeb1",
  "softwareInformation": [
    {
     "name": "ECU Software XY12345",
      "softwareId": "SW123456789",
      "version": "1.2.0",
      "lastModifiedOn": "2023-03-21T08:17:29.187+01:00"
    },
    {
      "name": "Controller-SW",
      "softwareId": "SW987654321",
      "version": "3.0.0",
      "lastModifiedOn": "2024-04-30T08:17:29.187+01:00"
    }
  ]
}

CertificateSigningRequests​

The Certificate Signing Requests aspect model contains the essential information needed to request specific certificates for a unique ECU component via a Certificate Signing Request (CSR) and to validate and certificate the ECU against this data.

A CSR (Certificate Signing Request) is a 64-based PEM formatted and encrypted message to request a (digital) certificate. The CSR validates the information required by a specific certification authority (CA) to issue the associated certificate.

Aspect model in GitHub:

Example: Submodel CertificateSigningRequests​
{
    "certificateSigningRequestList": [
        {
            "certificateSigningRequest": "MIIC2TCCAToCAQAwgZwxEzARBgNVBAgTClByb2R1Y3Rpb24xDDAKBgNVBAcMA0FUTTESMBAGA1UEChMJQk1XIEdyb3VwMRcwFQYDVQQLEw5WZWhpY2xlUEtJLUVDVTEXMBUGA1UEAxMOSVBzZWMtaW50ZXJuYWwxMTAvBgNVBAUTKEVDVS1VSUQ6QzAwMDgyNDI3MUREQTYwMDAwMDAwMDAwMjdBQTg0MjQwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAShNm4y5Mdzu4b9xDW3TfBZr",
            "subjectLocality": "ATM--02",
            "subjectCommonName": "ID",
            "subjectSerialNumber": "SN12345678"
        },
        {
            "certificateSigningRequest": "MII3tbCCAToCAQAwgZwxEzARBgNVBAgTClByb2R1Y3Rpb24xDDAKBgNVBAcMA0FUTTESMBAGA1UEChMJQk1XIEdyb3VwMRcwFQYDVQQLEw5WZWhpY2xlUEtJLUVDVTEXMBUGA1UEAxMOSVBzZWMtaW50ZXJuYWwxMTAvBgNVBAUTKEVDVS1VSUQ6QzAwMDgyNDI3MUREQTYwMDAwMDAwMDAwMjdBQTg0MjQwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAShNm4y5Mdzu4b9xDW3TfBZr",
            "subjectLocality": "ATM--02",
            "subjectCommonName": "IPsec-Internal",
            "subjectSerialNumber": "SN12345678"
        }
    ]
}

SpecialCharacteristicMeasurement​

Special Characteristics are measureable and these measurements are of interest for a consumer who defined these characteristics. The proposal is a data model "result" which represents a measurement related to a specific measurement and product. A measurement result is identified by the identification of a characteristic and the product.

Aspect model in GitHub:

Example: Submodel SpecialCharacteristicMeasurement​

{
  "localIdentifiers": [
    {
      "value": "SN12345678",
      "key": "partInstanceId"
    },
    {
      "value": "SN12345678",
      "key": "manufactuererId"
    }
  ],
  "customerPartId": "PRT-12345",
  "revisionIndex": "01",
  "measurementType": "simple",
  "characteristicId": "S1",
  "results": [ ]
}

Due to the amount of different characteristics we opted not to require a specific format for the measurement objects contained in the "results": [ ] object list. We rather provide a set of format we recommend to use. These recommendations depend on the most common characteristics and their requirements for the results.

Simple Measurements​

We consider for characteristics a simple measurement if it just requires to measure a single value. For example the thickness of a rolled steel plate. We designed the measurement object to be able to represent any measurement where it is required to measure a value with a unit.

Data model | Attribute | Plausability | Type | Example | | :-- | :-- | :-- | :-- | | value | mandatory | string | -2.9426523E38 | | unit | mandatory | string | -eOMtThyhVNLWUZNRcBaQKxI | | measurementTimeStamp | mandatory | timestamp | 2024-10-01 |

Example: Submodel Simple Measurements

{
  "measurement" : {
    "value" : -2.9426523E38,
    "unit" : "eOMtThyhVNLWUZNRcBaQKxI"
  },
  "measurementTimestamp" : "2024-10-01"
}
Qualitative Measurements​

We consider a qualitative measurement a measurement where a value has to be extracted and a read Qualitity has to be determined. An example would be the serial number which has to be etched onto the product. The result of the etching has to be of a certain quality where this quality is measured by some metric.

Data model | Attribute | Plausability | Type | Example | | :-- | :-- | :-- | :-- | | extractedValue | mandatory | string | eOMtThyhVNLWUZNRcBaQKxI | | readQuality | mandatory | string | 5 | | measurementTimeStamp | mandatory | timestamp | 2024-10-01 |

Example: Submodel Qualitative Measurements

{
  "extractedValue" : "eOMtThyhVNLWUZNRcBaQKxI",
  "readQuality" : 5,
  "measurementTimestamp" : "2024-10-01"
}
Functional Measurements​

Functional Measurements are for characteristics where the result just confirms that the function is at it is expected.

Data model | Attribute | Plausability | Type | Example | | :-- | :-- | :-- | :-- | | value | mandatory | boolean | true | | measurementTimeStamp | mandatory | timestamp | 2024-10-01 |

Example

{
  "value" : true,
  "measurementTimestamp" : "2024-10-01"
}

Policies​

Access policies like the BPN access policy and Usage Policies / Contract Policies are described in the policy section of the Industry Core KIT.

NOTICE​

This work is licensed under the CC-BY-4.0.

  • SPDX-License-Identifier: CC-BY-4.0
  • SPDX-FileCopyrightText: 2023 BASF SE
  • SPDX-FileCopyrightText: 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
  • SPDX-FileCopyrightText: 2023 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. (represented by Fraunhofer ISST & Fraunhofer IML)
  • SPDX-FileCopyrightText: 2023 German Edge Cloud GmbH & Co. KG
  • SPDX-FileCopyrightText: 2023 Mercedes Benz AG
  • SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH
  • SPDX-FileCopyrightText: 2023 SAP SE
  • SPDX-FileCopyrightText: 2023 Siemens AG
  • SPDX-FileCopyrightText: 2023 T-Systems International GmbH
  • SPDX-FileCopyrightText: 2023 ZF Friedrichshafen AG
  • SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation
  • Source URL: https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/tree/main/docs-kits/kits/Traceability%20Kit (latest version)