refactor: rework introduction and related sections by juliapampus · Pull Request #113 · eclipse-dataspace-protocol-base/DataspaceProtocol

juliapampus · 2025-02-11T08:46:59Z

What this PR changes/adds

Restructures introduction sections.

Removes information model content incl. figures.
- Updates terms and definitions accordingly.
- Removes all terms that are not used in the specification files.
- Updates scope section.
Removes resource files with broken links for reasons of maintenance. Figures are listed via respec.
Adds style file that is required for TP figures.
Restructures README
Clean-up links to terminology.

Why it does that

Remove duplicated, outdated, and unnecessary non-normative content.

Further notes

Some of the removed contents (e.g., information model) should be transferred to the best practices document.

Linked Issue(s)

Closes #66
Closes #60

Please be sure to take a look at the contributing guidelines and our etiquette for pull requests.

jimmarino

I had some relatively minor comments. The one thing that I think needs to be clarified is that the specification is developed under Eclipse guidance.

jimmarino · 2025-02-11T17:15:28Z

README.md


-The web rendering of the spec represents the current state on this repo's main branch.
-https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/
+Since [Version 0.8](https://github.com/eclipse-dataspace-protocol-base/DataspaceProtocol/tree/main/releases/v0.8), the specification has been stable with changes in details. The latest release candidate ([2024-1](https://docs.internationaldataspaces.org/ids-knowledgebase/dataspace-protocol)) of the Dataspace Protocol specification is considered stable. It has been developed under the governance of the [International Data Spaces Association](https://internationaldataspaces.org/). Further changes shall not affect conformity. 


We have to be very careful here. The specification has been developed under Eclipse governance, not IDSA

I'd argue that 2024-1 is not the "latest release candidate" but rather the latest release. I'd rather be careful with claims toward conformity.

I think we should leave the version history here and add a sentence clarifying that after 2024-1 the project changed the governance from IDSA to Eclipse.

Always happy about discussions about moved content, especially from its authors.

Let me come up with a better proposal.

Acknowledged, but for me not possible during this week.

I've added a new commit:

Previous versions of the Dataspace Protocol (0.8 and 2024-1) have been developed and released under the governance of the International Data Spaces Association (IDSA).

Subsequent versions of the Dataspace Protocol are maintained and developed within the Eclipse Dataspace Protocol project associated with the Eclipse Dataspace Working Group, under the governance of the Eclipse Foundation (EF). Version 2024-1 marks the initial contribution to the Eclipse Dataspace Protocol project by the IDSA.

WDYT?

README.md

jimmarino · 2025-02-11T17:22:31Z

specifications/common/introduction.md

-on the level of trust, on organizational levels, and on legal levels.
-The aspect of cross-dataspace communication is not subject of this document, as this is addressed by the [=Dataspaces=]'
-organizational and legal agreements.
+The __Dataspace Protocol__ is used in the context of [=Dataspaces=] as described and defined in the subsequent sections with the purpose to support _interoperability_. In this context, the specification provides fundamental technical interoperability for [=Participants=] in [=Dataspaces=]. Beyond the technical interoperability measures described in this specification, semantic interoperability should be addressed by the [=Participants=]. On the perspective of the [=Dataspace=], interoperability needs to be addressed also on the level of trust, on organizational levels, and on legal levels. The aspect of cross-dataspace communication is not subject of this document, as this is addressed by the [=Dataspaces=]' organizational and legal agreements.


This may be straying from the purpose of this PR but I think these types of statements should be in the best practices guide because they deal with "SHOULDs" but not "MUSTs"

This is the introduction which shall provide also some context to the document. I would leave it here, but agree that in the main body of the document we should consider the MUSTs and leave the SHOULDs, in general, to the best practices

My first thought was to move this to "scope". Then I read the ISO rules again and recognized that the current scope should also not be part of the scope as this must be normative. The more I think about this, the more I agree to remove this phrase and also shorten the scope section drastically. Please check the latest changes.

arnoweiss

Mostly respec related stuff

arnoweiss · 2025-02-12T07:27:51Z

README.md


-The web rendering of the spec represents the current state on this repo's main branch.
-https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/
+Since [Version 0.8](https://github.com/eclipse-dataspace-protocol-base/DataspaceProtocol/tree/main/releases/v0.8), the specification has been stable with changes in details. The latest release candidate ([2024-1](https://docs.internationaldataspaces.org/ids-knowledgebase/dataspace-protocol)) of the Dataspace Protocol specification is considered stable. It has been developed under the governance of the [International Data Spaces Association](https://internationaldataspaces.org/). Further changes shall not affect conformity. 


I'd argue that 2024-1 is not the "latest release candidate" but rather the latest release. I'd rather be careful with claims toward conformity.

README.md

specifications/catalog/catalog.protocol.md

index.html

ssteinbuss

Minor editorial changes requested

ssteinbuss · 2025-02-12T08:34:58Z

README.md


-The web rendering of the spec represents the current state on this repo's main branch.
-https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/
+Since [Version 0.8](https://github.com/eclipse-dataspace-protocol-base/DataspaceProtocol/tree/main/releases/v0.8), the specification has been stable with changes in details. The latest release candidate ([2024-1](https://docs.internationaldataspaces.org/ids-knowledgebase/dataspace-protocol)) of the Dataspace Protocol specification is considered stable. It has been developed under the governance of the [International Data Spaces Association](https://internationaldataspaces.org/). Further changes shall not affect conformity. 


I think we should leave the version history here and add a sentence clarifying that after 2024-1 the project changed the governance from IDSA to Eclipse.

README.md

ssteinbuss · 2025-02-12T08:40:49Z

specifications/common/introduction.md

-on the level of trust, on organizational levels, and on legal levels.
-The aspect of cross-dataspace communication is not subject of this document, as this is addressed by the [=Dataspaces=]'
-organizational and legal agreements.
+The __Dataspace Protocol__ is used in the context of [=Dataspaces=] as described and defined in the subsequent sections with the purpose to support _interoperability_. In this context, the specification provides fundamental technical interoperability for [=Participants=] in [=Dataspaces=]. Beyond the technical interoperability measures described in this specification, semantic interoperability should be addressed by the [=Participants=]. On the perspective of the [=Dataspace=], interoperability needs to be addressed also on the level of trust, on organizational levels, and on legal levels. The aspect of cross-dataspace communication is not subject of this document, as this is addressed by the [=Dataspaces=]' organizational and legal agreements.


This is the introduction which shall provide also some context to the document. I would leave it here, but agree that in the main body of the document we should consider the MUSTs and leave the SHOULDs, in general, to the best practices

jimmarino · 2025-02-12T09:27:31Z

I think we should leave the version history here and add a sentence clarifying that after 2024-1 the project changed the governance from IDSA to Eclipse.

I think the correct way to describe this is the initial contribution came from IDSA, not that the governance changed. My concern is that we must be clear that the IP review process was followed.

Co-authored-by: Jim Marino <jim.marino@gmail.com> Co-authored-by: Arno Weiß <86715435+arnoweiss@users.noreply.github.com>

ssteinbuss · 2025-02-12T09:48:37Z

I think we should leave the version history here and add a sentence clarifying that after 2024-1 the project changed the governance from IDSA to Eclipse.

I think the correct way to describe this is the initial contribution came from IDSA, not that the governance changed. My concern is that we must be clear that the IP review process was followed.

I like that. That is the correct way that the initial contribution was made by IDSA. Thx

juliapampus · 2025-02-12T10:54:38Z

I've addressed your comments. Please review README, "introduction" and "scope" again carefully.

specifications/common/terminology.md

docs: restructure README

892f185

juliapampus changed the title ~~docs: restructure README~~ refactor: rework introduction and related sections Feb 11, 2025

juliapampus added 7 commits February 11, 2025 09:51

refactor: shorten introduction

28345ab

feat: remove model section

c0e1282

refactor: add class definitions to protocols

6cfebbe

refactor: rework scope section

9901194

refactor: remove resources

88fbefe

fix: revert removal of style file

0273baa

fix: update links to terms

b44effe

juliapampus marked this pull request as ready for review February 11, 2025 17:12

juliapampus requested review from arnoweiss, jimmarino, mkollenstart and ssteinbuss February 11, 2025 17:12

jimmarino reviewed Feb 11, 2025

View reviewed changes

arnoweiss suggested changes Feb 12, 2025

View reviewed changes

ssteinbuss requested changes Feb 12, 2025

View reviewed changes

juliapampus and others added 2 commits February 12, 2025 10:41

chore: apply suggestions from code review

d88a617

Co-authored-by: Jim Marino <jim.marino@gmail.com> Co-authored-by: Arno Weiß <86715435+arnoweiss@users.noreply.github.com>

fix: resolve broken link to terminology

9a6b735

juliapampus added 3 commits February 12, 2025 11:12

docs: clearify version history

80ff513

chore: add minor changes

394b6a0

chore: remove non-normative phrases from scope

c809af5

juliapampus requested review from arnoweiss, jimmarino and ssteinbuss February 12, 2025 10:54

arnoweiss approved these changes Feb 12, 2025

View reviewed changes

mkollenstart approved these changes Feb 13, 2025

View reviewed changes

jimmarino approved these changes Feb 13, 2025

View reviewed changes

ssteinbuss reviewed Feb 20, 2025

View reviewed changes

specifications/common/terminology.md Show resolved Hide resolved

ssteinbuss mentioned this pull request Feb 20, 2025

Aligning definitions with 20151 Dataspace Concepts and Characteristics #121

Closed

ssteinbuss approved these changes Feb 20, 2025

View reviewed changes

ssteinbuss merged commit 276fec9 into eclipse-dataspace-protocol-base:main Feb 20, 2025

Conversation

juliapampus commented Feb 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR changes/adds

Why it does that

Further notes

Linked Issue(s)

Uh oh!

jimmarino left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juliapampus Feb 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arnoweiss left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ssteinbuss left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jimmarino commented Feb 12, 2025

Uh oh!

ssteinbuss commented Feb 12, 2025

Uh oh!

juliapampus commented Feb 12, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

juliapampus commented Feb 11, 2025 •

edited

Loading

juliapampus Feb 12, 2025 •

edited

Loading