Eclipse Dataspace Components

Best practices and recommendations

Mon, 01 Jan 0001 00:00:00 +0000

1. Preface

This document aims at giving guidelines and recommendations to developers who want to use or extend EDC or EDC modules in their applications, to DevOps engineers who are tasked with packaging and operating EDC modules as runnable application images.

Connector

Mon, 01 Jan 0001 00:00:00 +0000

Module `accesstokendata-store-sql`

Artifact: org.eclipse.edc:accesstokendata-store-sql:0.17.0

Categories: None

Extension points

None

Extensions

Class: `org.eclipse.edc.connector.dataplane.store.sql.SqlAccessTokenDataStoreExtension`

Name: “Sql AccessTokenData Store”

Overview: Provides Sql Store for {@link AccessTokenData} objects

Configuration

Key	Required	Type	Default	Pattern	Min	Max	Description
`edc.sql.store.accesstokendata.datasource`	`*`	`string`	`default`				The datasource to be used

Provided services

org.eclipse.edc.connector.dataplane.spi.store.AccessTokenDataStore

Referenced (injected) services

org.eclipse.edc.transaction.datasource.spi.DataSourceRegistry (required)
org.eclipse.edc.transaction.spi.TransactionContext (required)
org.eclipse.edc.connector.dataplane.store.sql.schema.AccessTokenDataStatements (optional)
java.time.Clock (required)
org.eclipse.edc.spi.types.TypeManager (required)
org.eclipse.edc.sql.QueryExecutor (required)
org.eclipse.edc.sql.bootstrapper.SqlSchemaBootstrapper (required)

Module `aes-encryption`

Artifact: org.eclipse.edc:aes-encryption:0.17.0

Json LD

Mon, 01 Jan 0001 00:00:00 +0000

JSON-LD in EDC

Here is a simple example taken from json-ld.org

{
 "@context": "https://json-ld.org/contexts/person.jsonld",
 "@id": "http://dbpedia.org/resource/John_Lennon",
 "name": "John Lennon",
 "born": "1940-10-09",
 "spouse": "http://dbpedia.org/resource/Cynthia_Lennon"
}

It’s similar on how a Person would be represented in JSON, with additional known properties such as @context and @id.

The @id is used to uniquely identify an object.

The @context is used to define how terms should be interpreted and help expressing specific identifier with shorthand names instead of IRI.

Policy Monitor

Mon, 01 Jan 0001 00:00:00 +0000

Some transfer types, once accepted by the provider, never reach the COMPLETED state. Streaming and HTTP transfers in consumer pull scenario are examples of this. In those scenarios the transfer will remain active (STARTED) until it gets terminated either manually by using the transfer processes management API, or automatically by the policy monitor, if it has been configured in the EDC runtime.

The policy monitor (PolicyMonitorManager) is a component that watches over ongoing transfers on the provider side and ensures that the associated policies are still valid. The default implementation of the policy monitor tracks the monitored transfer processes in it’s own entity PolicyMonitorEntry stored in the PolicyMonitorStore.

Programming Primitives

Mon, 01 Jan 0001 00:00:00 +0000

1 State machines

EDC is asynchronous by design, which means that processes are processed in such a way that they don’t block neither the runtime nor the caller. For example starting a contract negotiation is a long-running process and every contract negotiation has to traverse a series of states, most of which involve sending remote messages to the counterparty. These state transitions are not guaranteed to happen within a certain time frame, they could take hours or even days.

Protocol Extensions

Mon, 01 Jan 0001 00:00:00 +0000

Protocol Extensions
- 1. RemoteMessage
  - 1.1 Delivering messages with RemoteMessageDispatcher
  - 1.2 Handling incoming messages with protocol services
- 2. DSP protocol implementation

The EDC officially supports the Dataspace protocol using the HTTPs bindings, but since it is an extensible platform, multiple protocol implementations can be supported for inter-connectors communication. Each supported protocols is identified by a unique key used by EDC for dispatching a remote message.

Service Layers

Mon, 01 Jan 0001 00:00:00 +0000

This document describes the EDC service layers.

Dependency Injection

Mon, 01 Jan 0001 00:00:00 +0000

1. Registering a service implementation

As a general rule, the module that provides the implementation also should register it with the ServiceExtensionContext. This is done in an accompanying service extension. For example, providing a “FunkyDB” based implementation for a FooStore (stores Foo objects) would require the following classes:

Developer Tools

Mon, 01 Jan 0001 00:00:00 +0000

1. Introduction

We provide two Gradle plugins that could be used to simplify your build/documentation efforts.

Identity-Hub

Mon, 01 Jan 0001 00:00:00 +0000

Module `attestation-api`

Artifact: org.eclipse.edc:attestation-api:0.17.0

Categories: None

Extension points

None

Extensions

Class: `org.eclipse.edc.issuerservice.api.admin.credentials.IssuerAttestationAdminApiExtension`

Name: “Issuer Service Credentials Admin API Extension”

Overview: No overview provided.

Configuration_None_

Provided services

None

Referenced (injected) services

org.eclipse.edc.web.spi.WebService (required)
org.eclipse.edc.issuerservice.spi.issuance.attestation.AttestationDefinitionService (required)
org.eclipse.edc.api.auth.spi.AuthorizationService (required)

Module `common-core`

Artifact: org.eclipse.edc:common-core:0.17.0

Categories: None

Extension points

None

Extensions

Class: `org.eclipse.edc.identityhub.DiscriminatorMappingExtension`

Name: “Discriminator Mapping Extension”

Overview: No overview provided.

Configuration

Key	Required	Type	Default	Pattern	Min	Max	Description
`edc.identityhub.discriminator.<alias>.value`	`*`	`string`	``				the full value for the discriminator
`edc.identityhub.discriminator.<alias>.alias`	`*`	`string`	``				the discriminator alias

Provided services

org.eclipse.edc.identityhub.spi.transformation.DiscriminatorMappingRegistry

Referenced (injected) services

None

OpenApi spec

Mon, 01 Jan 0001 00:00:00 +0000

It is possible to generate an OpenApi spec in the form of a *.yaml file by invoking two simple Gradle tasks.

Generate `*.yaml` files

Every module (=subproject) that contains REST endpoints is scanned for Jakarta Annotations which are then used to generate a *.yaml specification for that particular module. This means that there is one *.yamlfile per module, resulting in several *.yaml files.

Custom Data Plane

Mon, 01 Jan 0001 00:00:00 +0000

When the data-plane is not embedded, EDC uses the Data Plane Signaling protocol (DPS) for the communication between control plane and data plane. In this chapter we will see how to leverage on DPS for writing a custom data plane from scratch.

For example purposes, this chapter contains JS snippets that use express as web framework.

Data Persistence with PostgreSQL

Mon, 01 Jan 0001 00:00:00 +0000

By default, the in-memory stores are provided by the dependency injection, the sql implementations can be used by simply registering the relative extensions (e.g. asset-index-sql, contract-negotiation-store-sql, …).

Extension Model

Mon, 01 Jan 0001 00:00:00 +0000

1. Extension basics

Three things are needed to register an extension module with the EDC runtime:

a class that implements ServiceExtension
a provider-configuration file
adding the module to your runtime’s build file. EDC uses Gradle, so your runtime build file should contain

runtimeOnly(project(":module:path:of:your:extension"))

Extensions should not contain business logic or application code. Their main job is to

Logging

Mon, 01 Jan 0001 00:00:00 +0000

A comprehensive and consistent way of logging is a crucial pillar for operability. Therefore, the following rules should be followed:

Logging component

Logs must only be produced using the Monitor service, which offers 4 different log levels:

`severe`

Error events that might lead the application to abort or still allow it to continue running.

Used in case of an unexpected interruption of the flow or when something is broken, i.e. an operator has to take action. e.g. service crashes, database in illegal state, … even if there is chance of self recovery.

Writing tests

Mon, 01 Jan 0001 00:00:00 +0000

1. Adding EDC test fixtures

To add EDC test utilities and test fixtures to downstream projects, simply add the following Gradle dependency:

Known Friends

Mon, 01 Jan 0001 00:00:00 +0000

To get to know how we define “adoptions” and see how to submit a feature, please take a look at our guidelines for submitting adoption requests.

Filter

Title	Description	Links
EDC Extension for Asset Administration Shell (AAS)	Asset Administration Shell (AAS) data can be manually shared over the EDC by linking an EDC Asset to the HTTP endpoint of the specific AAS element. Additionally, contracts and policies have to be defined for each element. In order to minimize configuration effort and prevent errors, this extension is able to link existing AAS services and its elements to the EDC automatically. Furthermore, this extension can also start an AAS service by reading an static AAS model file. A default contract and policy can be chosen to be applied for all elements. For critical elements, additional contracts and policies can be placed. External changes to the structure of an AAS are automatically synchronized by the extension.	Link to repository
Eclipse Tractus-X EDC	Extension of the EDC Connector for “Manufacturing-X” dataspaces that are based on the Catena-X data ecosystem. The Tractus-X EDC focus in the automatization of the data exchange and contract negotiation withouth human interaction. Additionally it offers a number of optimizations like the “Endpoint Data Reference” (EDR) interface which simplifies the data negotiation and transfer mechanism, handling token callback for the business applications. It provides also a token refresh handler, an optional BPN-DID resolution service for easier identification of the partners and “restricts” the usage of “odrl” policies based on legal requirements, provided by several company lawyers, which stablished the goverance/regulatory framework from Catena-X, enabling the data exchange in a data ecosystem, via this EDC Connector, to be done with legal coverage. Additionally, this EDC Connector offers a deployment configuration via Helm Charts and an extensive architecture documentation from Business/Adoption Level to Development/Operation Level in the Eclipse Tractus-X Connector KIT.	Link to repository
Data tracking by auditing data	Proof of concept of how to track data usage by aggregating audit-logs of different components in a single instance: The work presents a first proof of concept of how traceability of data usage can be implemented using the EDC Connector event framework and audit logging. In this PoC, the traceability of data is limited to the AWS dataplane. The EDC Connector logs which exact assets are stored with which key in the AWS bucket. With this information, data usage can be traced from the shared logs of the EDC Connector and the AWS S3 bucket. Elasticsearch was chosen as the instance to merge both logs in this project. A simple Python script takes over the analysis of the log data.	Link to repository
EDC GUI	Extended EDC Data Dashboard that integrates the open-source EDC Connector interfaces while adding asset properties and form validation, providing design and UX changes, and introducing configuration profiles.	Link to repository
EDC Connector HTTP client	An HTTP client to communicate with the EDC Connector for Node.js and the browser.	Link to repository npm
Integration for Microsoft Dynamics 365 and Power Platform	The prototype demonstrates how to publish product information from a Microsoft Power App to a participant in an existing dataspace. The Microsoft Power Automate custom connector calls the EDC endpoints from the Nocode/lowcode platform to publish an asset and create a contract. This example shows the integration into the Microsoft Dataverse.	Link to repository
Silicon Economy EDC	The Silicon Economy EDC is a configured version from the Connector of the Eclipse Dataspace Components (EDC). It is used and specialized to easily integrate Silicon Economy components with the IDS.	Link to repository
EDC Extension for IONOS S3 storage	We are providing an EDC extension to allow the connector to save and to access files kept into an IONOS S3 storage	Link to repository
EDC metadata extractor extension	This extension is a PoC to automatically extract metadata of a file that can be used for further processing (e.g., calculating the FAIRness score).	Link to repository
Huawei Dataspace Components	Technology repository containing OBS (S3-compatible object storage hosted in the cloud) and GaussDB (a relational database based on Postgres 9.2.4 as data retention backend) extensions	Link to repository
A Rust client for EDC connector	A Rust HTTP client to communicate with the EDC Connector.	Link to repository Link to crates.io
EDC Connector TUI	A TUI client for EDC Connector written in Rust	Link to repository
…	…	…

Custom validation framework

Mon, 01 Jan 0001 00:00:00 +0000

The validation framework hooks into the normal Jetty/Jersey request dispatch mechanism and is designed to allow users to intercept the request chain to perform additional validation tasks. In its current form it is intended for intercepting REST requests. Users can elect any validation framework they desire, such as jakarta.validation or the Apache Commons Validator, or they can implement one themselves.

Getting adopted

Mon, 01 Jan 0001 00:00:00 +0000

This document is intended as guideline for contributors who either already have implemented a feature, e.g. an extension, or intend to do so, and are looking for ways to upstream that feature into the EDC.

There are currently two possible levels of adoption for the EDC project:

incorporate a feature as core EDC component
reference a feature as “friend”

Get referenced as “friend”

This means we will add a link to our known friends list, where we reference projects and features that we are aware of. These are repositories that have no direct affiliation with EDC and are hosted outside the eclipse-edc GitHub organization. We call this a “friend” of EDC (derived from the C++ friend class concept). In order to become a “friend” of EDC, we do a quick scan of the code base to make sure it does not contain anything offensive, or that contradicts our code of conduct, ethics or other core OSS values.

Release process

Mon, 01 Jan 0001 00:00:00 +0000

EDC is a set of java modules, that are released all together as a whole with a single version number across all the different code repositories, that are, to date:

Note: the Technology repositories are not considered part of the core release and the committer group is not accountable for unreleased versions of those components.

The released artifacts are divided in 3 categories:

Committers

Mon, 01 Jan 0001 00:00:00 +0000

Committers decide what code goes into the code base, they decide how a project builds, and they ultimately decide what gets delivered to the adopter community. With awesome power, comes awesome responsibility, and so the Open Source Rules of Engagement described by the Eclipse Foundation Development Process puts meritocracy on equal footing with transparency and openness: becoming a committer isn’t necessarily hard, but it does require a demonstration of merit:

Operate in an open, transparent, and meritocratic manner;
Write code (and other project content) and push it directly into the project’s source code repository;
Review contributions (merge and pull requests) from contributors;
Engage in the Intellectual Property Due Diligence Process;
Vote in committer and project lead elections;
Engage in the project planning process; and
Otherwise represent the interests of the open source project.

For Eclipse projects (and the open source world in general), committers are the ones who hold the keys. Committers are either appointed at the time of project creation or elected by the existing project team.

Instrumentation with Micrometer

Mon, 01 Jan 0001 00:00:00 +0000

EDC provides extensions for instrumentation with the Micrometer metrics library to automatically collect metrics from the host system, JVM, and frameworks and libraries used in EDC (including OkHttp, Jetty, Jersey and ExecutorService).

See sample 04.3 for an example of an instrumented EDC consumer.

Micrometer Extension

This extension provides support for instrumentation for some core EDC components:

Management API upcoming versions

Thu, 19 Feb 2026 00:00:00 +0000

The current, stable Management API of EDC Connector version 3 has served well during the last 2 years, but changes in the underlying protocols and the solidification of the EDC-V concept demand new versions.

Rationale

There will be 2 new Management API version releases.

Version 4

Version 4, which is already in its beta phase (as you can check in the OpenAPI documentation, so you can test it out and provide feedback), has been introduced to better align with the DSP 2025-1 spec.

Data Plane Signaling

Mon, 19 Jan 2026 00:00:00 +0000

Data Plane Signaling is a specification for interoperable communication between Dataspace Protocol Control Planes and Data Planes (github project).

We decided to fully adopt this specification and to deprecate the current approach. This will involve deprecating the current implementation of the communication layer between the Control Plane and Data Plane in addition to the EDC Data Plane Framework.

Rationale

The Data Plane Signaling specification addresses key architectural ambiguities by clearly delineating the roles of the Control Plane (orchestration and protocol-level authentication) and the Data Plane (actual data transfer and flow-specific authentication). This separation resolves design confusion, establishes symmetry between push and pull patterns, and, most importantly, creates a standard interface. This allows any application to become a compliant Data Plane, fostering innovation and moving the industry toward a future where data sharing is a seamless, integrated layer within sovereign applications, rather than a connector-centric task.

Mon, 01 Jan 0001 00:00:00 +0000

The Path to Version 1 for the Eclipse Dataspace Components

The Eclipse Dataspace Components (EDC) project has evolved significantly since its initial release. What started as an experimental reference implementation for dataspace connectors has grown into a mature, modular framework used in a variety of production-grade data sharing environments.

Over the past few years, the project has continuously expanded its capabilities, aligned with emerging dataspace specifications, and improved its operational maturity. With these developments in place, the project is now approaching an important milestone: Version 1.0.

Search Results

Mon, 01 Jan 0001 00:00:00 +0000

Eclipse Dataspace Components

Best practices and recommendations

1. Preface

Connector

Module accesstokendata-store-sql

Extension points

Extensions

Class: org.eclipse.edc.connector.dataplane.store.sql.SqlAccessTokenDataStoreExtension

Configuration

Provided services

Referenced (injected) services

Module aes-encryption

Json LD

Policy Monitor

Programming Primitives

1 State machines

Protocol Extensions

Service Layers

Dependency Injection

1. Registering a service implementation

Developer Tools

1. Introduction

Identity-Hub

Module attestation-api

Extension points

Extensions

Class: org.eclipse.edc.issuerservice.api.admin.credentials.IssuerAttestationAdminApiExtension

Configuration_None_

Provided services

Referenced (injected) services

Module common-core

Extension points

Extensions

Class: org.eclipse.edc.identityhub.DiscriminatorMappingExtension

Configuration

Provided services

Referenced (injected) services

OpenApi spec

Generate *.yaml files

Custom Data Plane

Data Persistence with PostgreSQL

Extension Model

1. Extension basics

Logging

Logging component

severe

Writing tests

1. Adding EDC test fixtures

Known Friends

Custom validation framework

Getting adopted

Get referenced as “friend”

Release process

Committers

Instrumentation with Micrometer

Micrometer Extension

Management API upcoming versions

Rationale

Version 4

Data Plane Signaling

Rationale

The Path to Version 1 for the Eclipse Dataspace Components

Search Results

Module `accesstokendata-store-sql`

Class: `org.eclipse.edc.connector.dataplane.store.sql.SqlAccessTokenDataStoreExtension`

Module `aes-encryption`

Module `attestation-api`

Class: `org.eclipse.edc.issuerservice.api.admin.credentials.IssuerAttestationAdminApiExtension`

Module `common-core`

Class: `org.eclipse.edc.identityhub.DiscriminatorMappingExtension`

Generate `*.yaml` files

`severe`