Industry DTR Usage

Models
Services
- AasService

Models

Endpoint

The Endpoint model represents the access point for interacting with a specific resource or service in the Digital Twin Registry (DTR). It defines how external systems can communicate with a digital twin or its associated submodels.

Python

from tractusx_sdk.industry.models.aas.v3 import Endpoint

endpoint = Endpoint(
    interface="SUBMODEL-3.0",
    protocolInformation=ProtocolInformation
)

Explanation of Parameters

interface: Specifies the interface type used by the endpoint. For example, "SUBMODEL-3.0" indicates that the endpoint adheres to the Submodel 3.0 interface specification.
protocolInformation: An instance of the ProtocolInformation model that provides details about the communication protocol, such as security attributes, endpoint type, and other protocol-specific configurations.

ProtocolInformation

The ProtocolInformation model represents the details of the communication protocol used by an endpoint in the Digital Twin Registry (DTR). It provides the necessary metadata to define how external systems can interact with a digital twin or its submodels, including protocol type, version, security attributes, and additional protocol-specific configurations.

Python

from tractusx_sdk.industry.models.aas.v3 import ProtocolInformation

protocolInformation=ProtocolInformation(
    href=href_url,
    endpointProtocol="HTTP",
    endpointProtocolVersion=["1.1"],
    subprotocol="DSP",
    subprotocolBody=subprotocol_body_str,
    subprotocolBodyEncoding="plain",
    securityAttributes=[
        ProtocolInformationSecurityAttributes
    ], 
)

Explanation of Parameters

href: The URL or address of the endpoint. This is the primary access point for interacting with the resource.
endpointProtocol: Specifies the communication protocol used by the endpoint.
endpointProtocolVersion: A list of protocol versions supported by the endpoint.
subprotocol: Defines a subprotocol used in conjunction with the main protocol.
subprotocolBody: A string containing additional information or metadata specific to the subprotocol.
subprotocolBodyEncoding: Specifies the encoding format of the subprotocolBody.
securityAttributes: A list of security attributes (ProtocolInformationSecurityAttributes) that define the security requirements or configurations for the endpoint.

ProtocolInformationSecurityAttributes

The ProtocolInformationSecurityAttributes model represents the security attributes associated with an endpoint in the Digital Twin Registry (DTR). These attributes define the security requirements or configurations needed to interact with the endpoint, ensuring secure communication and data exchange.

Python

from tractusx_sdk.industry.models.aas.v3 import ProtocolInformationSecurityAttributes

ProtocolInformationSecurityAttributes(
    type=ProtocolInformationSecurityAttributesTypes,
    key="NONE",
    value="NONE",
)

Explanation of Parameters

type: Specifies the type of security attribute. This is an enumeration from ProtocolInformationSecurityAttributesTypes, which defines the available security attribute types.
key: Represents the key or identifier for the security attribute.
value: Represents the value associated with the security attribute.

ProtocolInformationSecurityAttributesTypes

The ProtocolInformationSecurityAttributesTypes is an enumeration (Enum) that defines the possible types of security attributes for endpoints in the Digital Twin Registry (DTR). These attributes specify the security mechanisms required to interact with an endpoint, ensuring secure communication and data exchange.

Python

from tractusx_sdk.industry.models.aas.v3 import ProtocolInformationSecurityAttributesTypes

type=ProtocolInformationSecurityAttributesTypes.NONE

Possible Values

NONE: Indicates that no specific security attributes are required for the endpoint.
RFC_TLSA: Refers to the use of TLSA (Transport Layer Security Authentication) as defined in RFC 6698.
W3C_DID: Refers to the use of Decentralized Identifiers (DIDs) as specified by the W3C DID specification.

ShellDescriptor

The ShellDescriptor model represents the metadata and structure of an Asset Administration Shell (AAS) in the Digital Twin Registry (DTR). It provides information about the digital twin, including its unique identifiers and associated specific asset identifiers.

Python

from tractusx_sdk.industry.models.aas.v3 import ShellDescriptor

shell = ShellDescriptor(
    id=aas_id.urn,
    globalAssetId=global_id.urn,
    specificAssetIds=specific_asset_ids,
)

Explanation of Parameters

id: The unique identifier of the Asset Administration Shell (AAS).
globalAssetId: The global identifier of the asset associated with the shell.
specificAssetIds: A list of specific asset identifiers (SpecificAssetId objects) that provide additional identification details for the asset. These identifiers can include key-value pairs that uniquely describe the asset.

SubModelDescriptor

The SubModelDescriptor model represents the metadata and access information for a specific submodel of a digital twin in the Digital Twin Registry (DTR). Submodels define specific aspects or views of a digital twin, and the SubModelDescriptor provides the necessary details to describe and access these submodels.

Python

from tractusx_sdk.industry.models.aas.v3 import SubModelDescriptor

submodel = SubModelDescriptor(
    id=submodel_id.urn,
    idShort=aspect_id_name,
    semanticId=semantic_id_reference,
    endpoints=[endpoint],
)

Explanation of Parameters

id: The unique identifier of the submodel.
idShort: A human-readable short identifier for the submodel.
semanticId: A reference to the semantic definition of the submodel. This links the submodel to its semantic meaning or standard, ensuring interoperability and understanding across systems.
endpoints: A list of Endpoint objects that define how the submodel can be accessed. Each endpoint specifies the protocol, address, and other details required to interact with the submodel.

SpecificAssetId

The SpecificAssetId model represents a unique identifier for a specific asset in the Digital Twin Registry (DTR). It is used to link a digital twin to a physical or logical asset by providing additional identification details.

Python

from tractusx_sdk.industry.models.aas.v3 import SpecificAssetId

specific_customer_part_asset_id = SpecificAssetId(
    name="customerPartId",
    value=customer_part_id,
    externalSubjectId=Reference
)

Explanation of Parameters

name: The key or name of the specific asset identifier. This describes the type of identifier being provided.
value: The value of the specific asset identifier.
externalSubjectId: A reference to an external subject associated with the asset.

Reference

The Reference model represents a link to an external resource or entity in the Digital Twin Registry (DTR). It is used to associate elements, such as assets or submodels, with external definitions, systems, or identifiers. This ensures interoperability and traceability across different systems.

Python

from tractusx_sdk.industry.models.aas.v3 import Reference

externalSubjectId=Reference(
    type=ReferenceTypes,
    keys=[
        ReferenceKey,
    ],
)

Explanation of Parameters

type: Specifies the type of reference. This is an enumeration from ReferenceTypes, which defines the kind of reference being used.
keys: A list of ReferenceKey objects that define the components of the reference.

ReferenceTypes

The ReferenceTypes model is an enumeration (Enum) that defines the possible types of references used in the Digital Twin Registry (DTR). These reference types specify the context or purpose of a reference, enabling elements in the registry (such as assets or submodels) to be linked to external resources, systems, or definitions.

Python

from tractusx_sdk.industry.models.aas.v3 import ReferenceTypes

ReferenceTypes.EXTERNAL_REFERENCE

Possible Values

MODEL_REFERENCE: Indicates that the reference points to a specific model or definition within the context of the Asset Administration Shell (AAS).
EXTERNAL_REFERENCE: Indicates that the reference points to an external resource or entity outside the Digital Twin Registry.

ReferenceKey

The ReferenceKey model represents a single key in a reference within the Digital Twin Registry (DTR). It is used to define the components of a Reference, specifying the type and value of the key. Each ReferenceKey contributes to forming a complete reference to an external or internal resource.

Python

from tractusx_sdk.industry.models.aas.v3 import ReferenceKey

ReferenceKey(
    type=ReferenceKeyTypes, value=bpn
)

Explanation of Parameters

type: Specifies the type of the key.
value: The actual value of the key.

ReferenceKeyTypes

The ReferenceKeyTypes model is an enumeration (Enum) that defines the possible types of keys used in a ReferenceKey within the Digital Twin Registry (DTR). These key types specify the kind of resource or element being referenced, ensuring clarity and consistency when linking elements in the registry to internal or external resources.

Python

from tractusx_sdk.industry.models.aas.v3 import ReferenceKeyTypes

type=ReferenceKeyTypes.GLOBAL_REFERENCE

Possible Values

ANNOTATED_RELATIONSHIP_ELEMENT: Represents a relationship element with additional annotations.
ASSET_ADMINISTRATION_SHELL: Refers to an Asset Administration Shell (AAS) itself.
BASIC_EVENT_ELEMENT: Represents a basic event element in the AAS, used to describe events triggered by the system.
BLOB: Refers to a Binary Large Object (BLOB) in the AAS, typically used to store binary data such as images or files.
CAPABILITY: Represents a capability element in the AAS, describing the ability of an asset to perform a specific function.
CONCEPT_DESCRIPTION: Refers to a semantic definition or concept in the AAS.
DATA_ELEMENT: Represents a generic data element in the AAS, used to store data values.
ENTITY: Represents an entity in the AAS, such as a physical or logical object.
EVENT_ELEMENT: Refers to an event element in the AAS, used to describe events triggered by the system.
FILE: Refers to a file element in the AAS.
FRAGMENT_REFERENCE: Represents a reference to a fragment of a resource or document.
GLOBAL_REFERENCE: Represents a globally recognized reference to an external resource or entity.
IDENTIFIABLE: Refers to an identifiable element in the AAS, which has a unique identifier.
MULTI_LANGUAGE_PROPERTY: Represents a property in the AAS that supports multiple languages.
OPERATION: Refers to an operation element in the AAS, describing a function or method that can be executed.
PROPERTY: Represents a property in the AAS, typically a single value or attribute.
RANGE: Refers to a range element in the AAS, used to define a range of values.
REFERABLE: Represents an element in the AAS that can be referred to by a unique identifier.
REFERENCE_ELEMENT: Refers to a reference element in the AAS, used to link to other elements or resources.
RELATIONSHIP_ELEMENT: Represents a relationship element in the AAS, describing a relationship between two entities.
SUBMODEL: Refers to a submodel in the Asset Administration Shell (AAS).
SUBMODEL_ELEMENT: Refers to an element within a submodel.
SUBMODEL_ELEMENT_COLLECTION: Refers to a collection of submodel elements.
SUBMODEL_ELEMENT_LIST: Represents a list of submodel elements in the AAS, used to group related elements.

Result

The Result model is used to represent the outcome of an operation or request in the Digital Twin Registry (DTR). Specifically, it is designed to handle cases where the response is not a successful 2XX HTTP status code. This model provides a structured way to capture and analyze error messages or other details about the failed operation.

Services

The AasService is a service class provided by the Tractus-X SDK to interact with the Digital Twin Registry (DTR). It provides a set of methods to manage Asset Administration Shells (AAS), submodels, and their associated metadata. This service simplifies communication with the DTR by abstracting API calls into high-level methods.

Python

from tractusx_sdk.industry.services import AasService

aas_service = AasService(
    base_url=dtr_url,
    base_lookup_url=dtr_lookup_url,
    api_path=api_path,
)

Explanation of Parameters

base_url: The base URL of the Digital Twin Registry.
base_lookup_url: The base URL for lookup operations in the registry.
api_path: The API path for accessing the DTR endpoints.

Aas Service Methods

get_all_asset_administration_shell_descriptors

Retrieves all Asset Administration Shell (AAS) Descriptors from the Digital Twin Registry.

Args

limit (int, optional): Specifies the maximum number of shell descriptors to return in a single response.
cursor (str, optional): A server-generated identifier used for pagination to retrieve the next set of results.
asset_kind (AssetKind_3_0, optional): Filters the results by the kind of asset.
asset_type (str, optional): Filters the results by the type of asset. The value is automatically BASE64-URL-encoded.
bpn (str, optional): The Business Partner Number (BPN) used for authorization and filtering

Returns

GetAllShellDescriptorsResponse: Contains the retrieved shell descriptors and pagination metadata.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

get_asset_administration_shell_descriptor_by_id

Retrieves a specific Asset Administration Shell (AAS) Descriptor by its identifier.

Args

aas_identifier (str): The unique identifier of the Asset Administration Shell.
bpn (str, optional): The Business Partner Number (BPN) used for authorization. If provided, it is added as an Edc-Bpn header to the request.

Returns

ShellDescriptor: The requested Asset Administration Shell Descriptor object containing metadata about the AAS.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

update_asset_administration_shell_descriptor

Updates an existing Asset Administration Shell (AAS) Descriptor.

Args

aas_identifier (str): The unique identifier of the Asset Administration Shell.
shell_descriptor (ShellDescriptor): The updated ShellDescriptor object containing the new metadata for the AAS.
bpn (str, optional): The Business Partner Number (BPN) used for authorization. If provided, it is added as an Edc-Bpn header to the request.

Returns

None: Returned if the request is successful.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

delete_asset_administration_shell_descriptor

Deletes an existing Asset Administration Shell (AAS) Descriptor.

Args

aas_identifier (str): The unique identifier of the Asset Administration Shell.
bpn (str, optional): The Business Partner Number (BPN) used for authorization. If provided, it is added as an Edc-Bpn header to the request.

Returns

None: Returned if the request is successful.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

get_submodel_descriptors_by_aas_id

Retrieves all Submodel Descriptors associated with a specific Asset Administration Shell (AAS).

Args

aas_identifier (str): The unique identifier of the Asset Administration Shell.
limit (int, optional): Specifies the maximum number of shell descriptors to return in a single response.
cursor (str, optional): A server-generated identifier used for pagination to retrieve the next set of results.
bpn (str, optional): The Business Partner Number (BPN) used for authorization and filtering

Returns

GetSubmodelDescriptorsByAssResponse: A response object containing a list of SubModelDescriptor objects in the result field and a pagination metadata in the paging_metadata field.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ValueError: Raised if the limit parameter is provided but is less than 1.
ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

get_submodel_descriptor_by_ass_and_submodel_id

Retrieves a specific Submodel Descriptor by its identifier and parent AAS identifier.

Args

aas_identifier (str): The unique identifier of the Asset Administration Shell.
submodel_identifier (str): The unique identifier of the Submodel to retrieve.
bpn (str, optional): The Business Partner Number (BPN) used for authorization.

Returns

SubModelDescriptor: The requested Submodel Descriptor object containing metadata about the submodel.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

create_asset_administration_shell_descriptor

Creates a new Asset Administration Shell (AAS) Descriptor in the Digital Twin Registry.

Args

shell_descriptor (ShellDescriptor): The ShellDescriptor object containing the metadata for the new AAS to be created.
bpn (str, optional): The Business Partner Number (BPN) used for authorization.

Returns

ShellDescriptor: The created Asset Administration Shell Descriptor object, including server-assigned fields such as unique identifiers.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

create_submodel_descriptor

Creates a new Submodel Descriptor in the Digital Twin Registry.

aas_identifier (str): The unique identifier of the Asset Administration Shell.
submodel_identifier (str): The unique identifier of the Submodel to retrieve.
bpn (str, optional): The Business Partner Number (BPN) used for authorization.

Returns

SubModelDescriptor: The created Submodel Descriptor object, including server-assigned fields such as unique identifiers.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

update_submodel_descriptor

Updates an existing Submodel Descriptor.

Args

aas_identifier (str): The unique identifier of the Asset Administration Shell.
submodel_identifier (str): The unique identifier of the Submodel to retrieve.
submodel_descriptor (SubModelDescriptor): The updated SubModelDescriptor object containing the new metadata for the Submodel.
bpn (str, optional): The Business Partner Number (BPN) used for authorization.

Returns

None: Returned if the request is successful.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

delete_submodel_descriptor

Deletes an existing Submodel Descriptor.

Args

aas_identifier (str): The unique identifier of the Asset Administration Shell.
submodel_identifier (str): The unique identifier of the Submodel to retrieve.
bpn (str, optional): The Business Partner Number (BPN) used for authorization.

Returns

None: Returned if the request is successful.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

get_description

Retrieves the service description, which presents the capabilities of the server, in particular which profiles they implement.

Returns

ServiceDescription: A ServiceDescription object containing details about the server's capabilities if the request is successful.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

get_assets_ids_by_asset_administration_shell_id

Retrieves all asset IDs associated with a specific Asset Administration Shell (AAS).

Args

aas_identifier (str): The unique identifier of the Asset Administration Shell.
bpn (str, optional): The Business Partner Number (BPN) used for authorization.

Returns

List[SpecificAssetId]: A list of SpecificAssetId objects if the request is successful. Each SpecificAssetId contains details such as the key and value of the asset ID.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

create_all_asset_ids_links_by_asset_administration_shell_id

Creates links between an Asset Administration Shell (AAS) and a list of assets IDs.

Args

aas_identifier (str): The unique identifier of the Asset Administration Shell.
list_of_asset_ids (List[SpecificAssetId]): A list of SpecificAssetId objects representing the asset IDs to link to the AAS.
bpn (str, optional): The Business Partner Number (BPN) used for authorization.

Returns

List[SpecificAssetId]: A list of SpecificAssetId objects if the request is successful. Each SpecificAssetId contains details such as the key and value of the asset ID.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

delete_all_asset_ids_links_by_asset_administration_shell_id

Deletes all links between an Asset Administration Shell (AAS) and its associated asset IDs.

Args

aas_identifier (str): The unique identifier of the Asset Administration Shell.
bpn (str, optional): The Business Partner Number (BPN) used for authorization.

Returns

None: Returned if the request is successful.
Result: A result object is returned if the request fails with a non-2XX status code, providing details about the error.

Raises

ConnectionError: Raised if there is a network connectivity issue.
TimeoutError: Raised if the request times out.
ValidationError: Raised if the JSON response does not match the expected model.

NOTICE

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

SPDX-License-Identifier: CC-BY-4.0
SPDX-FileCopyrightText: 2025 Contributors to the Eclipse Foundation
Source URL: https://github.com/eclipse-tractusx/tractusx-sdk