SDK Structure and Components

The Eclipse Tractus-X SDK follows a modular architecture that provides clean separation of concerns and maximum flexibility for dataspace application development.

Overview

The SDK is organized into three main libraries, each serving distinct purposes:

• Dataspace Library

  ---

  Core connector services and Eclipse Tractus-X Connector integration for basic dataspace operations.

  Learn more

• Industry Library

  ---

  Digital Twin Registry and Submodel Server integration for industry-specific data models and standards.

  Learn more

• Extensions Library

  ---

  Use case-specific extensions and add-on functionality for custom business logic implementations.

  Learn more

Architecture Layers

The SDK implements a layered architecture that promotes clean code organization and maintainability:

graph LR
    A["🎯 Your App"] --> B["📋 Services"]
    B --> C["🎮 Controllers"]
    C --> D["🔌 Adapters"]
    D --> E["🌐 EDC Connector"]

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style E fill:#e8f5e8

Library Structure

1. Dataspace Library (tractusx_sdk.dataspace)

The foundation layer for all dataspace interactions:

Text Only

tractusx_sdk/dataspace/
├── adapters/          # HTTP communication adapters
│   └── connector/     # Connector-specific adapters
├── controllers/       # API request handlers
│   └── connector/     # Connector API controllers
├── managers/          # Authentication and connection management
│   └── connection/    # Connection lifecycle management
├── models/            # Data models and schemas
│   ├── connection/    # Connection-related models
│   └── connector/     # Connector data models
├── services/          # High-level business logic
│   ├── connector/     # Connector service implementations
│   └── discovery/     # Discovery service integrations
└── tools/             # Utility functions and helpers

Key Components:

• Service Factory - Creates connector services with proper configuration
• Base Connector Service - Core abstraction for EDC connector interactions
• Connection Managers - Handles connection lifecycle and authentication
• HTTP Adapters - Low-level HTTP communication with connectors
• Discovery Services - Dataspace discovery and catalog operations

2. Industry Library (tractusx_sdk.industry)

Specialized components for industry-specific use cases:

Text Only

tractusx_sdk/industry/
├── adapters/          # Industry-specific adapters
│   └── submodel_adapters/  # Submodel service adapters
├── models/            # Industry data models
│   ├── aas/          # Asset Administration Shell models
│   └── v3/           # Version 3 specific models
└── services/          # Industry services
    └── discovery/     # Industry discovery services

Key Features:

• Digital Twin Registry - Integration with DTR for asset discovery
• Asset Administration Shell - AAS 3.0 compliant implementations
• BPN Discovery - Business Partner Number resolution services
• Submodel Lifecycle - Complete submodel management operations
• Industry Models - Specialized data models and schemas

3. Extensions Library (tractusx_sdk.extensions)

Extensible framework for custom use cases:

Text Only

tractusx_sdk/extensions/
└── semantics/         # Semantic model extensions

Capabilities:

• Custom Logic - Integration of domain-specific business rules
• Semantic Models - Advanced semantic model processing
• Workflow Engine - Use case-specific process automation
• Plugin Architecture - Extensible framework support
• Domain Extensions - Industry-specific customizations

Design Patterns

Factory Pattern

The SDK extensively uses the Factory Pattern for service creation:

Python

from tractusx_sdk.dataspace.services.connector.service_factory import ServiceFactory

# Create connector service
connector_service = ServiceFactory.get_connector_consumer_service(
    dataspace_version="jupiter",
    base_url="https://connector.example.com",
    dma_path="/management",
    headers=headers,
    logger=logger
)

Adapter Pattern

Adapters provide clean abstractions over external protocols:

Python

# High-level service call
assets = connector_service.get_assets()

# Internally uses adapters for HTTP communication
# → Controller handles business logic
# → Adapter handles HTTP protocol details
# → External EDC connector receives request

Multi-Version Support

The SDK supports multiple dataspace versions for backward compatibility:

• Jupiter - Stable version for production use
• Saturn - Latest version with newest features

Python

# Version-specific service creation
jupiter_service = ServiceFactory.get_connector_consumer_service(
    dataspace_version="jupiter",  # Stable
    # ... other config
)

saturn_service = ServiceFactory.get_connector_consumer_service(
    dataspace_version="saturn",   # Latest
    # ... other config
)

Integration Patterns

Complete Dataspace Integration

graph TD
    A[Your Application] --> B[Dataspace Foundation Library]
    A --> C[Industry Foundation Library]
    A --> D[Extensions]

    B --> E[EDC Connector]
    B --> F[Discovery Services]
    B --> G[Authentication]

    C --> H[Digital Twin Registry]
    C --> I[Submodel Services]

    D --> J[Custom Use Cases]
    D --> K[Semantic Extensions]

Key Benefits

• Quick to Start

  ---

  Get up and running in under 5 minutes with minimal configuration.

• Easy to Use

  ---

  Pythonic API with type hints, auto-completion, and comprehensive examples.

• Production Ready

  ---

  Built-in authentication, error handling, and retry mechanisms.

• Extensible

  ---

  Multi-version support and factory patterns for maximum flexibility.

Development Tips

🚀 Start Simple: Begin with basic connector operations before adding complexity
🔄 Reuse Services: Create service instances once and reuse them
📝 Enable Logging: Use verbose mode during development for better debugging
🧪 Test Incrementally: Test each component separately before integration

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