Skip to content

Dataspace Connector Usage

Models

General Values

This section defines the configuration values, metadata, and policies required for interacting with the Eclipse Dataspace Connector (EDC). These values are used to configure endpoints, define asset details, and enforce policies for secure and compliant data exchange.

Python
edc_url="http://dataprovider-controlplane.tx.test"
dataspace_version = "jupiter"
headers={"X-Api-Key": "TEST1", "Content-Type": "application/json"}
oid = "201"
data_address = {"type": "test_type", "value": "test_value"}
context = {"odrl": "http://www.w3.org/ns/odrl/2/"}
properties = {"prop_key": "prop_value"}
private_properties = {"private_key": "private_value"}
permissions = [{"action": "permission"}]
prohibitions = [{"action": "prohibitions"}]
obligations = [{"action": "obligations"}]
edc_url2="http://dataconsumer-1-controlplane.tx.test"
counter_party_address = edc_url + "/api/v1/dsp"
counter_party_id = "BPNL00000003AYRE"
context2 = [
"https://w3id.org/tractusx/policy/v1.0.0",
"http://www.w3.org/ns/odrl.jsonld",
{ "@vocab": "https://w3id.org/edc/v0.0.1/ns/" }
]
asset_id = "200"
offer_id = "MjAw:MjAw:ZDE5ZjA4Y2QtMzg1Ny00MTEzLWFjZjQtZmFhNWQ1MDdjYmE3"
offer_policy_data = {
    "@context": "http://www.w3.org/ns/odrl.jsonld",
    "odrl:permission": {
    "odrl:action": {
        "odrl:type": "USE"
    },
    "odrl:constraint": {
        "odrl:or": {
        "odrl:leftOperand": "BusinessPartnerNumber",
        "odrl:operator": {
            "@id": "odrl:eq"
        },
        "odrl:rightOperand": "BPNL00000003AZQP"
        }
    }
    },
    "odrl:prohibition": [],
    "odrl:obligation": []
}
callback_addresses = []
filter = [
    {
    "operandLeft": "contractNegotiationId",
    "operator": "=",
    "operandRight": "bf936f50-e2e7-4007-ba0d-7541be1721ae"
    }
]

Asset Model

The Asset Model represents the metadata and configuration required to define an asset in the Eclipse Dataspace Connector (EDC). Assets are the core entities exchanged or managed in a dataspace, and they include details such as identifiers, data addresses, and associated properties

Python
from tractusx_sdk.dataspace.models.connector.model_factory import ModelFactory

asset = ModelFactory.get_asset_model(
    dataspace_version=dataspace_version,
    oid=oid,
    data_address=data_address,
    context=context,
    properties=properties,
    private_properties=private_properties
)

Explanation of Parameters

  • dataspace_version: Specifies the version of the dataspace being used. Ensures compatibility with the EDC.
  • oid: The unique identifier for the asset being defined. This is used to distinguish the asset in the dataspace.
  • data_address: A dictionary that specifies the location or type of the data associated with the asset.
  • context: Defines the namespace for interpreting metadata and policies.
  • properties: A dictionary of metadata associated with the asset. These are general properties that describe the asset.
  • private_properties: A dictionary of sensitive or restricted metadata associated with the asset. These properties are not publicly accessible.

Catalog Model

The Catalog Model represents the metadata and configuration required to query and retrieve available assets from a counterparty in the Eclipse Dataspace Connector (EDC). It is used to interact with the catalog endpoint of a counterparty to discover assets that can be negotiated or exchanged.

Python
from tractusx_sdk.dataspace.models.connector.model_factory import ModelFactory

catalog_model = ModelFactory.get_catalog_model(
    dataspace_version=dataspace_version,
    counter_party_address=counter_party_address,
    counter_party_id=counter_party_id
)

Explanation of Parameters

  • dataspace_version: Specifies the version of the dataspace being used. Ensures compatibility with the EDC.
  • counter_party_address: The endpoint URL of the counterparty's catalog service. This is where the catalog query will be sent.
  • counter_party_id: The unique identifier of the counterparty. This is used to identify the counterparty in the dataspace.

Contract Definition Model

The Contract Definition Model represents the metadata and configuration required to define a contract in the Eclipse Dataspace Connector (EDC). Contracts are used to enforce policies and rules for data exchange between parties in the dataspace.

Python
from tractusx_sdk.dataspace.models.connector.model_factory import ModelFactory

contract_definition = ModelFactory.get_contract_definition_model(
    dataspace_version=dataspace_version,
    oid=oid,
    access_policy_id=oid,
    contract_policy_id=oid
)

Explanation of Parameters

  • dataspace_version: Specifies the version of the dataspace being used. Ensures compatibility with the EDC.
  • oid: The unique identifier for the contract definition. This is used to distinguish the contract in the dataspace.
  • access_policy_id: The identifier of the access policy associated with the contract. This policy defines who can access the asset.
  • contract_policy_id: The identifier of the contract policy associated with the contract. This policy defines how the asset can be used.

Contract Negotiation Model

The Contract Negotiation Model represents the metadata and configuration required to initiate and manage contract negotiations in the Eclipse Dataspace Connector (EDC). Contract negotiations are a key step in establishing agreements between parties for data exchange, ensuring that both access and usage policies are agreed upon before the transfer of data.

Python
from tractusx_sdk.dataspace.models.connector.model_factory import ModelFactory

contract_negotiation_model = ModelFactory.get_contract_negotiation_model(
    dataspace_version=dataspace_version,
    counter_party_address=counter_party_address,
    offer_id=offer_id,
    asset_id=asset_id,
    provider_id=counter_party_id,
    offer_policy=offer_policy_data
)

Explanation of Parameters

  • dataspace_version: Specifies the version of the dataspace being used. Ensures compatibility with the EDC.
  • counter_party_address: The endpoint URL of the counterparty's negotiation service. This is where the negotiation request will be sent.
  • counter_party_id: The unique identifier of the counterparty (e.g., Business Partner Number). This is used to identify the counterparty in the dataspace.
  • offer_id: The unique identifier of the data offer being negotiated. This links the negotiation to a specific asset and its associated policies.
  • asset_id: The unique identifier of the asset being negotiated. This ensures that the negotiation is tied to a specific resource.
  • provider_id: The unique identifier of the data provider. This is used to identify the provider in the dataspace.
  • offer_policy: A dictionary defining the policy associated with the data offer. This includes permissions, prohibitions, and obligations that govern the use of the asset.

Policy Model

The Policy Model represents the metadata and configuration required to define policies in the Eclipse Dataspace Connector (EDC). Policies are used to enforce rules and constraints for data access and usage, ensuring compliance with predefined terms during data exchange

Python
from tractusx_sdk.dataspace.models.connector.model_factory import ModelFactory

policy = ModelFactory.get_policy_model(
    dataspace_version=dataspace_version,
    oid=oid,
    context=context
)

Explanation of Parameters

  • dataspace_version: Specifies the version of the dataspace being used. Ensures compatibility with the EDC.
  • oid: The unique identifier for the policy. This is used to distinguish the policy in the dataspace.
  • context: Defines the namespace for interpreting the policy.

QuerySpec Model

The QuerySpec Model represents the metadata and configuration required to define query specifications in the Eclipse Dataspace Connector (EDC). Query specifications are used to filter and retrieve specific assets or data from a catalog or other data sources in the dataspace.

Python
from tractusx_sdk.dataspace.models.connector.model_factory import ModelFactory

queryspec_edr_model = ModelFactory.get_queryspec_model(
    dataspace_version=dataspace_version,
    filter_expression=filter
)

Explanation of Parameters

  • dataspace_version: Specifies the version of the dataspace being used. Ensures compatibility with the EDC.
  • filter: A list of conditions used to filter the query results. Each condition specifies an operand, operator, and value.
  • limit: Specifies the maximum number of results to return.
  • offset: Specifies the starting point for the query results.
  • sortOrder: Specifies the order in which the results should be sorted. Possible values are ASC (ascending) or DESC (descending).
  • sortField: Specifies the field by which the results should be sorted.

Transfer Process Model

The Transfer Process Model represents the metadata and configuration required to initiate and manage data transfers in the Eclipse Dataspace Connector (EDC). The transfer process is a critical step in the dataspace, enabling the secure and compliant exchange of data between parties.

Python
from tractusx_sdk.dataspace.models.connector.model_factory import ModelFactory

transfer_process_model = ModelFactory.get_transfer_process_model(
    dataspace_version=dataspace_version,
    counter_party_address=counter_party_address,
    contract_id="6d869fc1-2538-4888-a687-249a9016e6a6",
    transfer_type="HttpData-PULL",
    data_destination={"type": "HttpProxy"}
)

Explanation of Parameters

  • dataspace_version: Specifies the version of the dataspace being used. Ensures compatibility with the EDC.
  • counter_party_address: The endpoint URL of the counterparty's transfer service. This is where the transfer request will be sent.
  • contract_id: The unique identifier of the contract associated with the data transfer. This ensures that the transfer complies with the agreed-upon terms.
  • transfer_type: Specifies the type of data transfer. For example, "HttpData-PULL" indicates a pull-based HTTP data transfer.
  • data_destination: A dictionary specifying the destination for the transferred data. For example, {"type": "HttpProxy"} indicates that the data will be sent to an HTTP proxy.
  • callback_addresses: A list of callback URLs to notify the client about the status or events of the transfer process. These URLs are invoked during specific stages of the transfer lifecycle, such as completion or failure.

Services

EDC Service

The EDC Service is a central component that provides access to various controllers in the Eclipse Dataspace Connector (EDC). These controllers allow you to manage assets, catalogs, contracts, policies, and data transfers in the dataspace. The BaseConnectorService acts as a wrapper, providing a unified interface to interact with the EDC's Data Management API.

Text Only
from tractusx_sdk.dataspace.services.connector.v0_9_0.edc_service import ConnectorService

service = ConnectorService(base_url=self.base_url,
                            dma_path=self.dma_path,
                            headers=self.headers,)

service._asset_controller # alternative
service.assets()

service._catalog_controller # alternative
service.catalogs()

service._contract_agreement_controller # alternative
service.contract_agreements()

service._contract_definition_controller # alternative
service.contract_definitions()

service._contract_negotiation_controller # alternative
service.contract_negotiations()

service._edr_controller # alternative
service.edrs()

service._policy_controller # alternative
service.policies()

service._transfer_process_controller # alternative
service.transfer_processes()

Available Controllers

Adapters

DMA Adapter

The DMA Adapter (Data Management API Adapter) is a utility class used to interact with the Data Management API (DMA) of the Eclipse Dataspace Connector (EDC). It provides a convenient way to send requests to the DMA endpoints, such as managing assets, policies, and contracts.

Python
from tractusx_sdk.dataspace.adapters.connector.adapter_factory import AdapterFactory

adapter = AdapterFactory.get_dma_adapter(
    dataspace_version=dataspace_version,
    base_url=edc_url,
    dma_path="management",
    headers={"X-Api-Key": "TEST2", "Content-Type": "application/json"}
)

Explanation of Parameters

  • base_url: The base URL of the EDC's control plane. This is the root endpoint for all API requests.
  • dma_path: The path to the Data Management API. This is appended to the base_url to form the full API endpoint.
  • headers: A dictionary of HTTP headers required for API requests.

Controllers

Asset Controller

The Asset Controller is a component used to manage assets in the Eclipse Dataspace Connector (EDC). It provides methods for creating, updating, retrieving, and deleting assets, enabling seamless interaction with the EDC's Data Management API.

Python
from tractusx_sdk.dataspace.controllers.connector.controller_factory import ControllerFactory

asset_controller = ControllerFactory.get_asset_controller(
    dataspace_version=dataspace_version,
    adapter=adapter
)

Asset Controller Methods

Method Description Parameters
create Registers a new asset in the EDC AssetModel
update Updates the metadata or properties of an existing asset in the EDC AssetModel
get_by_id Retrieves the details of a specific asset by its unique identifier (OID). oid
delete Deletes an asset from the EDC by its unique identifier (OID). oid
get_all Retrieves a list of all assets currently registered in the EDC
query Queries the EDC for an asset based on specific criteria.

Catalog Controller

The Catalog Controller is a component used to interact with the catalog of a counterparty in the Eclipse Dataspace Connector (EDC). It provides methods for querying and retrieving available assets, enabling asset discovery and negotiation in the dataspace.

Python
from tractusx_sdk.dataspace.controllers.connector.controller_factory import ControllerFactory

catalog_controller = ControllerFactory.get_catalog_controller(
    dataspace_version=dataspace_version,
    adapter=consumer_adapter
)

Catalog Controller Methods

Method Description Parameters
get_catalog Retrieves the catalog of available assets from a counterparty's endpoint. CatalogModel

Contract Agreement Controller

The Contract Agreement Controller is a component used to manage contract agreements in the Eclipse Dataspace Connector (EDC). Contract agreements are established after successful contract negotiations and define the terms and conditions under which data can be exchanged between parties.

Python
from tractusx_sdk.dataspace.controllers.connector.controller_factory import ControllerFactory

contract_agreement_controller = ControllerFactory.get_contract_agreement_controller(
    dataspace_version=dataspace_version,
    adapter=consumer_adapter
)

Contract Agreement Controller Methods

Method Description Parameters
get_negotiation_by_id Retrieves the details of a specific contract negotiation by its unique identifier (OID). oid
get_by_id Retrieves the details of a specific contract agreement by its unique identifier (OID). oid
get_all Retrieves a list of all contract agreements or negotiations.
query Queries the EDC for a contract agreement based on specific criteria.

Contract Definition Controller

The Contract Definition Controller is a component used to manage contract definitions in the Eclipse Dataspace Connector (EDC). Contract definitions specify the terms, policies, and conditions under which data can be accessed and exchanged.

Python
from tractusx_sdk.dataspace.controllers.connector.controller_factory import ControllerFactory

contract_definition_controller =  ControllerFactory.get_contract_definition_controller(
    dataspace_version=dataspace_version,
    adapter=adapter
)

Contract Definition Controller Methods

Method Description Parameters
create Registers a new contract definition in the EDC. ContractDefinitionModel
update Updates the metadata or policies of an existing contract definition. ContractDefinitionModel
get_by_id Retrieves the details of a specific contract definition by its unique identifier (OID). oid
delete Deletes an contract definition from the EDC by its unique identifier (OID). oid
get_all Retrieves a list of all contract definition currently registered in the EDC
query Queries the EDC for an contract definition based on specific criteria.

Contract Negotiation Controller

The Contract Negotiation Controller is a component used to manage contract negotiations in the Eclipse Dataspace Connector (EDC). Contract negotiations are a critical step in establishing agreements between parties for data exchange. This controller facilitates the process of initiating, tracking, and managing contract negotiations.

Python
from tractusx_sdk.dataspace.controllers.connector.controller_factory import ControllerFactory

contract_negotiation_controller = ControllerFactory.get_contract_negotiation_controller(
    dataspace_version=dataspace_version,
    adapter=consumer_adapter
)

Contract Negotiation Controller Methods

Method Description Parameters
create Initiates a new contract negotiation with a counterparty. ContractNegotiationModel
terminate_by_id Terminates an ongoing contract negotiation by its unique identifier (OID). ContractNegotiationModel
get_agreement_by_negotiation_id Retrieves the contract agreement associated with a specific negotiation ID. oid
get_by_id Retrieves the details of a specific contract negotiation by its unique identifier (OID). oid
get_all Retrieves a list of all contract negotiations currently registered in the EDC.
get_state_by_id Retrieves the current state of a specific contract negotiation by its unique identifier (OID). oid
query Queries the EDC for a contract negotiation based on specific criteria.

EDR Controller

The EDR Controller (Endpoint Data Reference Controller) is a component used to manage Endpoint Data References (EDRs) in the Eclipse Dataspace Connector (EDC). EDRs are critical for enabling secure and efficient data transfers between parties in the dataspace. They provide the necessary information, such as endpoints and credentials, to access the data being shared.

Python
from tractusx_sdk.dataspace.controllers.connector.controller_factory import ControllerFactory

edr_controller = ControllerFactory.get_edr_controller(
    dataspace_version=dataspace_version,
    adapter=consumer_adapter
)

EDR Controller Methods

Method Description Parameters
get_data_address Retrieves the data address associated with a specific asset or contract. oid
refresh Refreshes the Endpoint Data Reference (EDR) for a specific asset or contract. oid
create Creates a new Endpoint Data Reference (EDR) for a specific contract. ContractNegotiationModel
get_all Retrieves a list of all Endpoint Data References (EDRs) currently registered in the EDC.
delete Deletes an Endpoint Data Reference (EDR) by its unique identifier. oid
query Queries the EDC for Endpoint Data References (EDRs) based on specific criteria.

Policy Controller

The Policy Controller is a component used to manage policies in the Eclipse Dataspace Connector (EDC). Policies define the rules, constraints, and permissions for accessing and using data in the dataspace.

Python
from tractusx_sdk.dataspace.controllers.connector.controller_factory import ControllerFactory

policy_controller = ControllerFactory.get_policy_controller(
    dataspace_version=dataspace_version,
    adapter=adapter
)

Policy Controller Methods

Method Description Parameters
create Registers a new policy in the EDC. PolicyModel
update Updates the metadata or rules of an existing policy in the EDC. PolicyModel
get_by_id Retrieves the details of a specific policy by its unique identifier (OID). oid
delete Deletes a policy from the EDC by its unique identifier (OID). oid
get_all Retrieves a list of all policies currently registered in the EDC.
query Queries the EDC for policies based on specific criteria.

Transfer Process Controller

The Transfer Process Controller is a component used to manage data transfer processes in the Eclipse Dataspace Connector (EDC). It facilitates the initiation, monitoring, and management of data transfers between parties in the dataspace. This controller ensures that data transfers comply with the terms of the associated contract agreements.

Python
from tractusx_sdk.dataspace.controllers.connector.controller_factory import ControllerFactory

transfer_process_controller = ControllerFactory.get_transfer_process_controller(
    dataspace_version=dataspace_version,
    adapter=consumer_adapter
)

Transfer Process Controller Methods

Method Description Parameters
create Initiates a new data transfer process. TransferProcessModel
terminate_by_id Terminates an ongoing data transfer process by its unique identifier (OID). TransferProcessModel
deprovision_by_id Deprovisions resources associated with a specific transfer process. oid
get_by_id Retrieves the details of a specific transfer process by its unique identifier (OID). oid
get_all Retrieves a list of all transfer processes currently registered in the EDC.
query Queries the EDC for transfer processes based on specific criteria.
get_state_by_id Retrieves the current state of a specific transfer process by its unique identifier (OID). oid

DMA Controller

The DMA Controller (Data Management API Controller) is a component used to interact with the Data Management API (DMA) of the Eclipse Dataspace Connector (EDC). It provides access to various controllers for managing assets, policies, contracts, and other resources in the dataspace.

Python
from tractusx_sdk.dataspace.controllers.connector.controller_factory import ControllerFactory

controllers = ControllerFactory.get_dma_controllers_for_version(
    dataspace_version=version,
    adapter=dma_adapter
)

This method retrieves a set of controllers compatible with the specified dataspace_version.

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

Eclipse Foundation

Eclipse Tractus-X

More

Copyright © 2025 Eclipse Tractus-X. Built with MkDocs and Material for MkDocs.