Skip to main content
Release: CX-Titan (Preview)

CX-0002 Digital Twins in Catena-X v2.4.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 APIsAPI An API is a way for two or more computer programs to communicate with each other. and Data Exchange in the Catena-X network

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 customersCustomer In the context of OSim, the receiver of produced goods from a supplier.
  • 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 assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. sufficient to meet the requirements of a set of use cases.

Any assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. - it can be an actual physical assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. 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 assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. can have more than one DT. However, each DTR may only contain a single DT for each assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer..
  • 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 assetsAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. (e.g., virtual prototype of a car) and instance assetsAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. (e.g., real car).
  • A DT can cover the whole assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. lifecycle including, e.g., the planning, production, sales, use, and decommissioning phases. However, in practice there may be more than one twin with different IDsIDS The International Data Space enables 'smart services' and business processes across companies and industries while ensuring data sovereignty and self-determined control of data use. representing different lifecycle phases, e.g., one twin for types and multiple twins for instances.
  • The DT represents current available information about an assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer., synchronized at a specified frequency and fidelity, which can be leveraged for simulation and business process integration.
  • 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 assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer.. Some basic information about the assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. being represented is part of each entry in a DTR.

For each assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer., 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 assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. 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 ModelAspect Model A formal, machine-readable semantic description (expressed with RDF/Turtle) of data accessible from an aspect. Note 1: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM) and be compliant with its validity rules. Note 2: Aspect Models are logical data models that can be used to detail a conceptual model to describe the semantics of runtime data related to a concept; elements of an Aspect Model can/should refer to terms of a standardized Business Glossary (if existing). conformant to CX-0003.

1.2.3 Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin.​

The Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. (AAS) is a key concept of Industry 4.0 (or "Industrie 4.0" in German), maintained by the Industrial Digital Twin Association (IDTA), and is used to describe an assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. 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 assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. by describing its Aspects for different use cases and data consumers.

The specifications of the AAS offers a set of standardized APIAPI An API is a way for two or more computer programs to communicate with each other. methods and resources to access data of a Digital Twin.

Also, an Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. 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 ModelAspect Model A formal, machine-readable semantic description (expressed with RDF/Turtle) of data accessible from an aspect. Note 1: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM) and be compliant with its validity rules. Note 2: Aspect Models are logical data models that can be used to detail a conceptual model to describe the semantics of runtime data related to a concept; elements of an Aspect Model can/should refer to terms of a standardized Business Glossary (if existing). 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

In general, the AAS has proven to be suitable for the following missions:

  • representing data exchanged in a standardized way between two parties (APIAPI An API is a way for two or more computer programs to communicate with each other. payload)
  • Providing uniform access to data exchanged between two parties (APIAPI An API is a way for two or more computer programs to communicate with each other. operations)
  • Data discovery for the assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. under consideration for exchange between two parties in a standardized way (Digital Twin Registry)

The Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. specifications are open source and can be found in the Content Hub of the IDTA and on GitHub: https://github.com/admin-shell-io/, repositories starting with "aas-specs". The html documentation can be found here: https://industrialdigitaltwin.io/aas-specifications/index/home/index.html.

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 assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. identifiers. The corresponding APIsAPI An API is a way for two or more computer programs to communicate with each other. 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. Besides discovery of registered participant agents in the dataspace (see standard CX-0018, section 2.6), 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

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], [RFC2119], [RFC8174] when, and only when, they appear in all capitals, as shown here.

1.5 Examples​

Examples can be found in the Tractus-X DTR's documentation and the 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 with a reference to a concrete Aspect ModelAspect Model A formal, machine-readable semantic description (expressed with RDF/Turtle) of data accessible from an aspect. Note 1: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM) and be compliant with its validity rules. Note 2: Aspect Models are logical data models that can be used to detail a conceptual model to describe the semantics of runtime data related to a concept; elements of an Aspect Model can/should refer to terms of a standardized Business Glossary (if existing)..

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 ModelAspect Model A formal, machine-readable semantic description (expressed with RDF/Turtle) of data accessible from an aspect. Note 1: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM) and be compliant with its validity rules. Note 2: Aspect Models are logical data models that can be used to detail a conceptual model to describe the semantics of runtime data related to a concept; elements of an Aspect Model can/should refer to terms of a standardized Business Glossary (if existing). via a defined interface.

Note 2 to entry: Aspects are registered (incl. their "APIAPI An API is a way for two or more computer programs to communicate with each other. 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 in the Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin.

[SOURCE: Eclipse Semantic Modeling Framework (ESMF), editorial changes and notes added]

Aspect ModelAspect Model A formal, machine-readable semantic description (expressed with RDF/Turtle) of data accessible from an aspect. Note 1: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM) and be compliant with its validity rules. Note 2: Aspect Models are logical data models that can be used to detail a conceptual model to describe the semantics of runtime data related to a concept; elements of an Aspect Model can/should refer to terms of a standardized Business Glossary (if existing).​

a formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect.

Note 1 to entry: An Aspect ModelAspect Model A formal, machine-readable semantic description (expressed with RDF/Turtle) of data accessible from an aspect. Note 1: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM) and be compliant with its validity rules. Note 2: Aspect Models are logical data models that can be used to detail a conceptual model to describe the semantics of runtime data related to a concept; elements of an Aspect Model can/should refer to terms of a standardized Business Glossary (if existing). 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 ModelsAspect Model A formal, machine-readable semantic description (expressed with RDF/Turtle) of data accessible from an aspect. Note 1: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM) and be compliant with its validity rules. Note 2: Aspect Models are logical data models that can be used to detail a conceptual model to describe the semantics of runtime data related to a concept; elements of an Aspect Model can/should refer to terms of a standardized Business Glossary (if existing). 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 ModelAspect Model A formal, machine-readable semantic description (expressed with RDF/Turtle) of data accessible from an aspect. Note 1: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM) and be compliant with its validity rules. Note 2: Aspect Models are logical data models that can be used to detail a conceptual model to describe the semantics of runtime data related to a concept; elements of an Aspect Model can/should refer to terms of a standardized Business Glossary (if existing). can/should refer to terms of a standardized Business Glossary (if existing).

Note 3 to entry: An Aspect ModelAspect Model A formal, machine-readable semantic description (expressed with RDF/Turtle) of data accessible from an aspect. Note 1: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM) and be compliant with its validity rules. Note 2: Aspect Models are logical data models that can be used to detail a conceptual model to describe the semantics of runtime data related to a concept; elements of an Aspect Model can/should refer to terms of a standardized Business Glossary (if existing). may describe the semantics of a Submodel.

[SOURCE: Eclipse Semantic Modeling Framework (ESMF), editorial changes and notes added]

Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin.​

standardized digital representation of an assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer.

Note 1 to entry: Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. and Administration Shell are used synonymously.

[SOURCE: IEC 63278-1:2023, 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 assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer..

[SOURCE: IIC Vocabulary IIC:IIVOC:V2.3:20201025, adapted (an assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer., process, or system was changed to an assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer.)]

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:2023, editorial changes]

Submodel​

representation of an aspect of an assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer.

[SOURCE: IEC 63278-1:2023]

SubmodelElement​

element of a Submodel

[SOURCE: IEC 63278-1:2023]

2. Digital Twin Registry APIAPI An API is a way for two or more computer programs to communicate with each other. for Solution Providers [NORMATIVE]​

2.1 APIAPI An API is a way for two or more computer programs to communicate with each other. Specification​

2.1.1 Standards and Profiles​

The specification Specification of the Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. - Part 2: Application Programming Interfaces is the basis for the Digital Twin Registry implementation in Catena-X.

The APIAPI An API is a way for two or more computer programs to communicate with each other. is offered as OpenAPI file in addition to its formal specification. The corresponding links can be found in the specification.

For relevant profiles of the Service Specifications see chapters on APIAPI An API is a way for two or more computer programs to communicate with each other. endpoints & resources.

2.1.2 APIAPI An API is a way for two or more computer programs to communicate with each other. Endpoints & resources​

The APIAPI An API is a way for two or more computer programs to communicate with each other. MUST be implemented as specified for the profiles:

Additionally, APIAPI An API is a way for two or more computer programs to communicate with each other. operations of the AAS not contained in these profiles but required for Digital Product Passport implementations MUST be provided.

The following profiles SHOULD be implemented:

  • Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. Registry Service Specification - Full Profile (SSP-001) and its bugfix releases

The following profiles MAY be implemented:

  • Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. Registry Service Specification - Query Profile (SSP-004) and its bugfix releases

  • Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. Registry Service Specification - Bulk Profile (SSP-001) and its bugfix releases

Note: GetAllAssetAdministrationShellIdsByAssetLink (GET /lookup/shells) is deprecated. Additionally, its substitute SearchAllAssetAdministrationShellIdsByAssetLink MUST be provided.

EXAMPLE for Self-Description (GetSelfDescription) of a Digital Twin Registry solution:

{
  "profiles": [
    "https://admin-shell.io/aas/API/3/0/DiscoveryServiceSpecification/SSP-001",
    "https://admin-shell.io/aas/API/3/1/DiscoveryServiceSpecification/SSP-002",
    "https://admin-shell.io/aas/API/3/2/DiscoveryServiceSpecification/SSP-002",
    "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-002",
    "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-005",
    "https://admin-shell.io/aas/API/3/1/AssetAdministrationShellRegistryServiceSpecification/SSP-005",
    "https://admin-shell.io/aas/API/3/2/AssetAdministrationShellRegistryServiceSpecification/SSP-005"
   ]
}

APIAPI An API is a way for two or more computer programs to communicate with each other. paths SHOULD be versioned only holding the major version of the AAS specification, for instance /v3/.

Note: The version segment of the APIAPI An API is a way for two or more computer programs to communicate with each other.-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 APIAPI An API is a way for two or more computer programs to communicate with each other. MUST use JSON as the payload transported via HTTPHTTP 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 can also be used for other purposes..

For explanation of data types see Specification of the Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. - Part 2: Application Programming Interfaces.

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 ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. - Part 2: Application Programming Interfaces.

3. Digital Twin Registry APIAPI An API is a way for two or more computer programs to communicate with each other. for Data Providers [NORMATIVE]​

3.1 APIAPI An API is a way for two or more computer programs to communicate with each other. Specification​

3.1.1 Standards and Profiles​

The specification of the Asset Administration Shell - Part 2: Application Programming Interfaces is the basis for the Digital Twin Registry implementation in Catena-X.

The APIAPI An API is a way for two or more computer programs to communicate with each other. is offered as OpenAPI file in addition to its formal specification published on https://industrialdigitaltwin.org/.

For relevant profiles of the Service Specifications see chapters on APIAPI An API is a way for two or more computer programs to communicate with each other. endpoints & resources.

3.1.2 APIAPI An API is a way for two or more computer programs to communicate with each other. Endpoints & resources​

The APIAPI An API is a way for two or more computer programs to communicate with each other. MUST be implemented as specified for the profiles:

The following profiles SHOULD be implemented:

  • Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. Registry Service Specification Query Profile and its bugfix releases

The WRITE operations of the following profile MAY be used to create and delete Digital Twins:

  • Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. Registry Service Specification Full Profile SSP-001 and its bugfix releases

The BULK operations of the following profile MAY be used to create, update and delete Digital Twins:

  • Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. Registry Service Specification Bulk Profile SSP-001

The same deviations are defined as for Digital Twin solution providers.

APIAPI An API is a way for two or more computer programs to communicate with each other. paths SHOULD be versioned only holding the major version of the AAS specification, for instance /v3/.

Note: However, the version segment of the APIAPI An API is a way for two or more computer programs to communicate with each other.-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 data consumer can assume that (when accessing a DTR) adding the path-elements /shell-descriptors/{{someAasId}} will reliably yield a response containing an AAS-Descriptor.

Access rules MAY be communicated with data consumers using the access rule modelling language in Specification of the Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. - Part 4: Security.

3.1.3 Available Data Types​

The APIAPI An API is a way for two or more computer programs to communicate with each other. MUST use JSON as payload transported via HTTPHTTP 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 can also be used for other purposes..

For explanation of data types see Specification of the Asset Administration Shell - Part 2: Application Programming Interfaces.

3.1.4 Representation in DSP catalogs​

If a Digital Twin Registry shall be made accessible via a DSP-compliant connector the data provider MUST expose a Dataset in the DSP catalog 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 of the DSP Catalog 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 ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. - Part 2: Application Programming Interfaces.

4. Submodel APIAPI An API is a way for two or more computer programs to communicate with each other. for Data Providers [NORMATIVE]​

4.1 APIAPI An API is a way for two or more computer programs to communicate with each other. Specification​

4.1.1 Standards and Profiles​

The Specification of the Asset Administration Shell - Part 2: Application Programming Interfaces is the basis for exchanging data via Digital Twins in Catena-X.

The APIAPI An API is a way for two or more computer programs to communicate with each other. is offered as OpenAPI file in addition to its formal specification published on https://industrialdigitaltwin.org/.

For relevant profiles of the Service Specifications see chapters on APIAPI An API is a way for two or more computer programs to communicate with each other. endpoints & resources.

APIAPI An API is a way for two or more computer programs to communicate with each other. paths SHOULD be versioned only holding the major version of the AAS specification, for instance /v3/.

Note: However, the version segment of the APIAPI An API is a way for two or more computer programs to communicate with each other.-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 data consumer can assume that when accessing data from a single registered Submodel with Endpoint interface "SUBMODEL-3.0" , adding the path-element $value will reliably yield a response containing the value-only serialization of a Submodel.

4.1.2 APIAPI An API is a way for two or more computer programs to communicate with each other. Endpoints & resources​

A Submodel that provides data MUST be implemented in conformance to the APIAPI An API is a way for two or more computer programs to communicate with each other.-definition of Submodel Service Specification - Value Profile (SSP-003) of the Submodel Service Specification and its bugfix releases.

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 be added to the Submodel Descriptor registered for the DT (SubmodelDescriptor/semanticId).
    • A data provider MUST add the unique identifier as specified in the use case standards of Catena-X 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 DataSet in the Data Providers DSP catalog that contains the Submodel.
    • dspEndpoint represents the endpoint of the Data Provider's Control Plane where the catalog containing the relevant 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.

Note: Beside Aspect ModelsAspect Model A formal, machine-readable semantic description (expressed with RDF/Turtle) of data accessible from an aspect. Note 1: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM) and be compliant with its validity rules. Note 2: Aspect Models are logical data models that can be used to detail a conceptual model to describe the semantics of runtime data related to a concept; elements of an Aspect Model can/should refer to terms of a standardized Business Glossary (if existing). standardized in Catena-X also other Aspects and Submodels may be registered, either conformant to proprietary standards or standards from other organizations. An Aspect ModelAspect Model A formal, machine-readable semantic description (expressed with RDF/Turtle) of data accessible from an aspect. Note 1: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM) and be compliant with its validity rules. Note 2: Aspect Models are logical data models that can be used to detail a conceptual model to describe the semantics of runtime data related to a concept; elements of an Aspect Model can/should refer to terms of a standardized Business Glossary (if existing). conformant to standard CX-0003 SHOULD be made available for these Aspects.

The following deviations are allowed, i.e., the following APIAPI An API is a way for two or more computer programs to communicate with each other. operations and operation parameters SHOULD be supported but these are not mandatory to be implemented.

  • provision of APIAPI An API is a way for two or more computer programs to communicate with each other. /description
  • support of APIAPI An API is a way for two or more computer programs to communicate with each other. operation /submodel (i.e., logical interface operation "GetSubmodel with logical parameter "Content"="Normal", the APIAPI An API is a way for two or more computer programs to communicate with each other. operation /submodel/$value extending the default operation's URL with the parameter /submodel/$value remains mandatory)
  • support of APIAPI An API is a way for two or more computer programs to communicate with each other. 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 APIAPI An API is a way for two or more computer programs to communicate with each other. /serialization
  • no support of logical parameter Content=Metadata, i.e., no support of APIAPI An API is a way for two or more computer programs to communicate with each other. operation with path parameter "$metamodel" /submodel$metamodel
  • no support of logical parameter Content=Reference, i.e., no support of APIAPI An API is a way for two or more computer programs to communicate with each other. operation with path parameter "$reference" /submodel/$reference
  • no support of logical parameter Content=Path, i.e., no support of APIAPI An API is a way for two or more computer programs to communicate with each other. 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:

{
  "id": "<unique ID of Submodel>",
  "semanticId": {
    "type": "ExternalReference",
    "keys": [
      {
        "type": "GlobalReference",
        "value": "urn:samm:io.catenax.material_demand:1.0.0#MaterialDemand"
      }
    ]
  },
  "endpoints": [
    {
      "protocolInformation": {
        "href": "https://edc.data.plane/<path>/submodel/$value",
        "endpointProtocol": "HTTP",
        "endpointProtocolVersion": [
          "1.1"
        ],
        "subprotocol": "DSP",
        "subprotocolBody": "id=123;dspEndpoint=https://edc.control.plane/",
        "subprotocolBodyEncoding": "plain"
      },
      "interface": "SUBMODEL-VALUE-3.2"
    }
  ]
}

Note: For endpoint interfaces "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 APIAPI An API is a way for two or more computer programs to communicate with each other. MUST use JSON as payload transported via HTTPHTTP 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 can also be used for other purposes..

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-0152).

The data provider MAY cluster several Submodels into one Dataset of the DSP catalog.

If a single Submodel is registered as a Dataset of the DSP catalog, it 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 AssetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. represents. The "aas-semantics" prefix MUST resolve to "https://admin-shell.io/aas/3/2/HasSemantics/", "https://admin-shell.io/aas/3/1/HasSemantics/" or "https://admin-shell.io/aas/3/0/HasSemantics/", depending on the version of the specification used for the Submodel.

For more details on conventions for the DSP catalog see CX-0018.

4.1.5 Error Handling​

Error response 501 Not Implemented MUST be used for APIAPI An API is a way for two or more computer programs to communicate with each other. operations and parameter values not yet supported.

For error handling see Specification of the Asset Administration Shell - Part 2: Application Programming Interfaces.

5. Submodel APIAPI An API is a way for two or more computer programs to communicate with each other. for Data Consumers [NORMATIVE]​

The specification Specification of the Asset Administration Shell - Part 2: Application Programming Interfaces is the basis for consuming data via Digital Twins in Catena-X.

The APIAPI An API is a way for two or more computer programs to communicate with each other. is offered as OpenAPI file in addition to its formal specification published on https://industrialdigitaltwin.org/.

This is the relevant service specification profile for data consumers:

The READ APIAPI An API is a way for two or more computer programs to communicate with each other. operations of the Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. profile SSP-003 of the Submodel Service Specification MAY be used to access the Submodels provided by data providers.

Depending on the value of Endpoint/interface the data consumer needs to react in different ways:

  • If Endpoint/interface equal to "SUBMODEL-3.x", for example "SUBMODEL-3.0", then the following behavior is to be implemented: 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.

  • If Endpoint/interface equal to "SUBMODEL-VALUE-3.x", e.g. "SUBMODEL-VALUE-3.2", then the endpoint in ProtocolInformation/href can be directly called.

Note: For Value-Only payload the minor version of the endpoint interface has no impact and can be ignored.

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 assetAsset On the Data Provider side, an Asset describes the data set which will be shared or can be consumed by a Data Consumer. and Submodel of interest is called with GET. Additionally, the data consumer MAY need to set parameters before calling the APIAPI An API is a way for two or more computer programs to communicate with each other. operation.

6. References​

6.1 Normative References​

  • Specification of the Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. - Part 1: Metamodel. V3.2, IDTA number: 01001-3-2. On IDTA Content Hub

  • Specification of the Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. - Part 2: Application Programming Interfaces. V3.2, IDTA number: 01002-03-2. On IDTA Content Hub

  • Specification of the Asset Administration ShellAsset Administration Shell The AAS is a digital representation of an asset; it is a form of a digital twin. - Part 4: Security. V3.1, IDTA number: 01004-3-1. On IDTA Content Hub

6.2 Non-Normative References​

This section is non-normative

6.3 Reference Implementations​

This section is non-normative

The following open-source project implements a Digital Twin Registry solution conformant to this standard:

Eclipse Tractus-X Digital Twin Registry

ANNEXES​

FIGURES​

This section is non-normative

Terminology - "Non-normative overview of relations between terms relevant in CX - 0002"

Architecture Overview

Copyright © 2026 Catena-X Automotive Network e.V. All rights reserved. For more information, please see Catena-X Copyright Notice.