Skip to content

Commit 276fec9

Browse files
juliapampusjimmarinoarnoweiss
authored
refactor: rework introduction and related sections (#113)
* docs: restructure README * refactor: shorten introduction * feat: remove model section * refactor: add class definitions to protocols * refactor: rework scope section * refactor: remove resources * fix: revert removal of style file * fix: update links to terms * chore: apply suggestions from code review Co-authored-by: Jim Marino <[email protected]> Co-authored-by: Arno Weiß <[email protected]> * fix: resolve broken link to terminology * docs: clearify version history * chore: add minor changes * chore: remove non-normative phrases from scope --------- Co-authored-by: Jim Marino <[email protected]> Co-authored-by: Arno Weiß <[email protected]>
1 parent 9c092c5 commit 276fec9

24 files changed

+253
-634
lines changed

README.md

Lines changed: 12 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,27 @@
11
# Dataspace Protocol
22

3-
## About versions of the Dataspace Protocol
3+
The __Dataspace Protocol__ is a set of specifications designed to facilitate interoperable data sharing between entities governed by usage control and based on Web technologies. These specifications define the schemas and protocols required for entities to publish data, negotiate [Agreements](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#dfn-agreement), and access data as part of a federation of technical systems termed a [Dataspace](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#dfn-dataspace).
44

5-
Since [version 0.8](https://github.com/eclipse-dataspace-protocol-base/DataspaceProtocol/tree/main/releases/v0.8)
6-
the specification has been stable with changes in details. Its The last release candidate ([2024-1](https://docs.internationaldataspaces.org/ids-knowledgebase/dataspace-protocol))
7-
of the Dataspace Protocol specification is considered to be stable. It was specified under governance of the [International Dataspaces Association](https://internationaldataspaces.org/).
8-
Further changes shall not affect conformity.
5+
The web rendering of the Dataspace Protocol represents the current state on this repo's main branch: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/.
96

10-
Now, the spec is maintained and developed by the [`eclipse-dataspace-protocol-base`](https://projects.eclipse.org/projects/technology.dataspace-protocol-base)
11-
Eclipse Project under the umbrella of the [Eclipse Dataspace Working Group](https://dataspace.eclipse.org/) (EDWG).
12-
The source of truth is this repository.
7+
## About versions
138

14-
The web rendering of the spec represents the current state on this repo's main branch.
15-
https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/
9+
Previous versions of the Dataspace Protocol ([0.8](https://github.com/International-Data-Spaces-Association/ids-specification/releases/tag/v0.8) and [2024-1](https://github.com/International-Data-Spaces-Association/ids-specification/releases/tag/2024-1)) have been developed and released under the governance of the [International Data Spaces Association (IDSA)](https://internationaldataspaces.org/).
1610

17-
> __NOTE:__ A versioning scheme beside the commits to the repository is not available but will be provided in the
18-
> future.
11+
Subsequent versions of the Dataspace Protocol are maintained and developed within the [Eclipse Dataspace Protocol project](https://projects.eclipse.org/projects/technology.dataspace-protocol-base) associated with the [Eclipse Dataspace Working Group](https://dataspace.eclipse.org/), under the governance of the [Eclipse Foundation (EF)](https://www.eclipse.org/). Version [2024-1](https://github.com/International-Data-Spaces-Association/ids-specification/releases/tag/2024-1) marks the initial contribution to the [Eclipse Dataspace Protocol project](https://projects.eclipse.org/projects/technology.dataspace-protocol-base) by the IDSA.
1912

20-
## Abstract
13+
## Best practices
2114

22-
The __Dataspace Protocol__ is a set of specifications designed to facilitate interoperable data sharing between entities
23-
governed by usage control and based on Web technologies. These specifications define the schemas and protocols required
24-
for entities to publish data, negotiate [Agreements](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#dfn-agreement), and access data as
25-
part of a federation of technical systems termed a [Dataspace](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#dfn-dataspace).
15+
Additional, non-normative information related to the Dataspace Protocol can be found in the [DSP Best Practices Guide](https://github.com/eclipse-dataspace-protocol-base/dsp_best_practices).
2616

27-
* [Introduction to the Dataspace Protocol](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#introduction-5)
28-
* [Scope of the Dataspace Protocol](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#scope)
17+
## How to contribute
2918

30-
## Introduction
31-
32-
## Best Practices
33-
34-
The Dataspace Protocol is under development and the working group is active on this draft, reviewed and improved the
35-
content multiple times. During the process several aspects were discussed, which are not considered part of the
36-
normative specification, but important to be documented as support for the users of this specification as best
37-
practices. The [Best Practices](https://github.com/eclipse-dataspace-protocol-base/dsp_best_practices) are non-normative.
38-
39-
Users of this specification are invited to provide feedback such as, but not limited to:
19+
Users of the Dataspace Protocol are invited to provide feedback such as, but not limited to:
4020

4121
* What information is missing?
4222
* What information, including examples, would you like to see?
4323
* What did you like in this document?
4424

45-
Please provide your feedback as a Discussion in this repository.
25+
Please provide your feedback as a [Discussion](https://github.com/eclipse-dataspace-protocol-base/DataspaceProtocol/discussions) in this repository.
26+
27+
For more information, please take a look at the [CONTRIBUTING](CONTRIBUTING.md) file.

index.html

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -43,9 +43,8 @@ <h1 id="title">Dataspace Protocol</h1>
4343
<section id='sotd'>
4444
<p>
4545
This version (2025-1) of the Dataspace Protocol specification is a release of the specification and considered to be
46-
stable. Further changes shall not affect conformity. Since <a href="https://github.com/International-Data-Spaces-Association/ids-specification/tree/main/releases/v0.8">version 0.8</a>
47-
the specification is stable with changes in details. All changes made to the specification can be reviewed in
48-
the GitHub repositories - up to and including `2024-1` under the governance of <a href="https://github.com/International-Data-Spaces-Association/ids-specification">IDSA</a>
46+
stable. Further changes shall not affect conformity. All changes made to the specification can be reviewed in
47+
the GitHub repositories - up to and including `2024-1` under the governance of the <a href="https://github.com/International-Data-Spaces-Association/ids-specification">IDSA</a>
4948
and with the <a href="https://github.com/eclipse-dataspace-protocol-base/DataspaceProtocol">EDWG</a> ever since.
5049
</p>
5150
</section>
@@ -62,10 +61,7 @@ <h1 id="title">Dataspace Protocol</h1>
6261
<section data-include="specifications/common/normative.references.md" data-include-format="markdown">
6362
</section>
6463

65-
<section data-include="specifications/model/terminology.md" data-include-format="markdown">
66-
</section>
67-
68-
<section data-include="specifications/model/model.md" data-include-format="markdown">
64+
<section data-include="specifications/common/terminology.md" data-include-format="markdown">
6965
</section>
7066

7167
<section data-include="specifications/common/common.protocol.md" data-include-format="markdown">

specifications/catalog/catalog.binding.https.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Catalog HTTPS Binding
1+
# Catalog HTTPS Binding {#catalog-http}
22

33
This specification defines a RESTful API over HTTPS for the [=Catalog Protocol=].
44

@@ -10,7 +10,7 @@ This specification defines a RESTful API over HTTPS for the [=Catalog Protocol=]
1010
URL is `api.example.com`, the URL `https://<base>/catalog/request` will map
1111
to `https//api.example.com/catalog/request`.
1212

13-
2. All request and response messages must use the `application/json` media type.
13+
2. All request and response [=Messages=] must use the `application/json` media type.
1414

1515
### Catalog Error
1616

specifications/catalog/catalog.protocol.md

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
# Catalog Protocol
1+
# Catalog Protocol {#catalog-protocol}
22

33
This document outlines the [=Catalog Protocol=]. The used terms are described in section [[[#terminology]]].
44

55
## Introduction
66

7-
The Catalog Protocol defines how a [=Catalog=] is requested from a [=Catalog Service=] by a [=Consumer=] using an
8-
abstract message exchange format. The concrete message exchange wire format is defined in the binding specifications.
7+
The [=Catalog Protocol=] defines how a [=Catalog=] is requested from a [=Catalog Service=] by a [=Consumer=] using an
8+
abstract [=Message=] exchange format. The concrete [=Message=] exchange wire format is defined in the binding specifications.
99

1010
The [=Catalog Protocol=] reuses properties from the DCAT and ODRL vocabularies with restrictions defined in this
1111
specification. This is done implicitly by the use of the JSON schemas and JSON-LD-contexts that are part of the DSP.
@@ -69,7 +69,8 @@ provided in protocol-dependent forms, e.g., for an HTTPS binding in the request
6969
| **Example** | [Catalog Example](message/example/catalog.json) |
7070
| **Properties** | <p data-include="message/table/catalog.html" data-include-format="html"></p> |
7171

72-
The [=Catalog=] contains all [Datasets](#dataset) which the requester shall see.
72+
* A [=Catalog=] _MUST_ have zero to many [=Datasets=]. (_NOTE: Since a Catalog may be dynamically generated for a request based on the requesting [=Participant=]'s credentials, it is possible for it to contain 0 matching [=Datasets=]._)
73+
* A [=Catalog=] _MUST_ have one to many [=Data Services=] that reference a [=Connector=] where [=Datasets=] may be obtained.
7374

7475
### ACK - Dataset
7576

@@ -80,6 +81,16 @@ The [=Catalog=] contains all [Datasets](#dataset) which the requester shall see.
8081
| **Example** | [Dataset Example](message/example/dataset.json) |
8182
| **Properties** | <p data-include="message/table/dataset.html" data-include-format="html"></p> |
8283

84+
* A [=Dataset=] _MUST_ have at least one `hasPolicy` attribute that contain an [=Offer=] defining the [=Policy=] associated with the [=Dataset=].
85+
* A [=Dataset=] _MUST_ hold at least one `Distribution` object in the `distribution` attribute.
86+
* Each `DataService` object _MUST HAVE_ at least one `DataService` which specifies where the distribution is obtained. Specifically, a `DataService` specifies the endpoint for initiating a [=Contract Negotiation=] and [=Transfer Process=].
87+
88+
An [=Offer=] contains the following attributes:
89+
90+
* An [=Offer=] _MUST_ have an `@id` that is a unique identifier.
91+
* An [=Offer=] _MUST_ be unique to a [=Dataset=] since the target of the [=Offer=] is derived from its enclosing context.
92+
* [=Offers=] _MUST NOT_ contain any `target` attributes. The value of the `target` attribute _MUST_ be the [=Dataset=] ID. (_Note: If the [=Offer=] is used in an enclosing [=Catalog=] or [=Dataset=], there must not be any `target` attribute set._)
93+
8394
### ERROR - Catalog Error
8495

8596
| | |
@@ -111,7 +122,7 @@ The [=Catalog Protocol=] is designed to be used by federated services without th
111122
Each [=Consumer=] is responsible for issuing requests to
112123
1..N [=Catalog Services=], and managing the results. It follows that a specific
113124
replication protocol is not needed, or more precisely, each [=Consumer=] replicates data
114-
from catalog services by issuing [Catalog Request Messages](#catalog-request-message).
125+
from [=Catalog Services=] by issuing [Catalog Request Messages](#catalog-request-message).
115126

116127
The discovery protocol adopted by a particular [=Dataspace=] defines how
117128
a [=Consumer=] discovers [=Catalog Services=].
@@ -134,7 +145,7 @@ all [=Datasets=] in the [=Catalog=] response and restrict access when a contract
134145
negotiated; or, require one or more proofs when the [Catalog Request](#catalog-request-message) is made and filter
135146
the [=Datasets=] accordingly. The latter option requires a mechanism for clients to
136147
discover the type of proofs that may be presented at request time. The specifics of proof types and presenting a proof
137-
during a [=Catalog=] request is outside the scope of the Dataspace Protocol.
148+
during a [=Catalog=] request is outside the scope of the [=Dataspace Protocol=].
138149
However, [=Catalog Protocol=] bindings should define a proof data endpoint for
139150
obtaining this information.
140151

specifications/common/common.protocol.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# General Common Protocol Requirements
1+
# Common Requirements {#requirements}
22

33
## Authorization
44

@@ -8,18 +8,18 @@ does not require authorization.
88

99
## Schemas, Contexts, and Message Processing
1010

11-
All protocol messages are normatively defined by a [[json-schema]]. This specification also uses JSON-LD 1.1 and provides
12-
a JSON-LD context to serialize data structures and message types as it facilitates extensibility. The JSON-LD context is
13-
designed to produce message serializations using compaction that validate against the Json Schema for the given message
14-
type. This allows implementations to choose whether to process messages as plain Json or as JSON-LD and maintain
11+
All protocol [=Messages=] are normatively defined by a [[json-schema]]. This specification also uses JSON-LD 1.1 and provides
12+
a JSON-LD context to serialize data structures and [=Message=] types as it facilitates extensibility. The JSON-LD context is
13+
designed to produce [=Message=] serializations using compaction that validate against the Json Schema for the given [=Message=]
14+
type. This allows implementations to choose whether to process [=Messages=] as plain JSON or as JSON-LD and maintain
1515
interoperability between those approaches. Extensions that use JSON-LD are encouraged to provide similar contexts that
1616
facilitate this approach to interoperability.
1717

1818
## Exposure of Dataspace Protocol Versions
1919

2020
### Generic Definition
2121

22-
[=Connectors=] implementing the Dataspace Protocol may operate on different versions. Therefore, it is necessary that
22+
[=Connectors=] implementing the [=Dataspace Protocol=] may operate on different versions. Therefore, it is necessary that
2323
they can discover the supported versions of each other reliably and unambiguously. Each [=Connector=] must expose
2424
information of at least one Dataspace Protocol Version it supports. The specifics of how this information is obtained
2525
its defined by specific protocol bindings.

specifications/common/introduction.md

Lines changed: 10 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,17 @@
11
# Introduction
22

3-
The __Dataspace Protocol__ is used in the context of [=Dataspaces=] as described and defined in the subsequent sections
4-
with the purpose to support interoperability.
5-
In this context, the specification provides fundamental technical interoperability for [=Participants=]
6-
in [=Dataspaces=].
7-
Beyond the technical interoperability measures described in this specification, semantic interoperability should also be
8-
addressed by the [=Participants=]. On the perspective of the [=Dataspace=], interoperability needs to be addressed also
9-
on the level of trust, on organizational levels, and on legal levels.
10-
The aspect of cross-dataspace communication is not subject of this document, as this is addressed by the [=Dataspaces=]'
11-
organizational and legal agreements.
3+
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=].
124

13-
The interaction of [=Participants=] in a [=Dataspace=] is conducted by the [=Participant Agents=],
14-
so-called [=Connectors=], which implement the protocols described above.
15-
While most interactions take place between [=Connectors=], some interactions with other systems are required.
16-
The figure below provides an overview on the context of this specification.
5+
This specification builds on protocols located in the [ISO OSI model (ISO/IEC 7498-1:1994)](https://www.iso.org/standard/20269.html) layers, like HTTPS. The purpose of this specification is to define interactions between systems independent of such protocols, but describing how to implement it in an unambiguous and extensible way. To do so, the [=Messages=] that are exchanged during the process are described in this specification and the states and their transitions are specified as state machines, based on the key terms and concepts of a [=Dataspace=]. On this foundation the bindings to data transfer protocols, like HTTPS, are described.
176

18-
An [=Identity Provider=] realizes the required interfaces and provides required information to implement the Trust
19-
Framework of a [=Dataspace=].
20-
The validation of the identity of a given [=Participant Agent=] and the validation of additional claims is a fundamental
21-
mechanism. The structure and content of such claims and identities may, however, vary between different [=Dataspaces=],
22-
as well as the structure of such an [=Identity Provider=], e.g. a centralized system, a decentralized system or a
23-
federated system. Other specifications define the respective functions.
7+
_Note: This specification does not cover the data transfer as such. While this is controlled by the [=Transfer Process Protocol=], e.g., the initiation of the transfer channels or their decomissioning, the data transfer itself and especially the handling of technical exceptions is an obligation to the transport protocol._
248

25-
A [=Connector=] will implement additional internal functionalities, like monitoring or policy engines, as appropriate.
26-
It is not covered by this specification if a [=Connector=] implements such or how.
9+
The classes and definitions used in this specification are reused from different standards and specifications as much as possible, in particular, DCAT [[?vocab-dcat-3]] and ODRL [[?odrl-model]]. As, however, the external definitions allow different interpretations or provide more attributes than required, this specification is leveraging _profiles_ of the original definitions rather than the complete original expressiveness. A _profile_ in this sense is a restriction or subset of an external definition, enforcing that every occurrence of an externally defined class is always conformant with the original definition. However, not every standard-compliant class might be compliant to the [=Dataspace=] profile. The profiles are not separate artifacts but implicitly contained in the JSON schemas for the [=Message Types=] of this specification.
2710

28-
The same applies for the actual data that is transferred between the systems. While this document does not define the
29-
transport protocol, the structure, syntax or semantics of the data, a specification for those aspects is required and
30-
subject to the agreements of the [=Participants=] or the [=Dataspace=].
11+
This specification is organized into the following documents:
3112

32-
![Overview on protocol and context](./figures/ProtocolOverview.png "Overview on protocol and context")
13+
* [[[#terminology]]] documents define key terms.
14+
* [[[#requirements]]] declares cross-cutting functions as, e.g., the declaration of supported versions of this protocol and common data processing rules.
15+
* [[[#catalog-protocol]]] and [[[#catalog-http]]] define how [=Catalogs=] are published and accessed as HTTPS endpoints respectively.
16+
* [[[#negotiation-protocol]]] and [[[#negotiation-http]]] documents that define how [=Contract Negotiations=] are conducted and requested via HTTPS endpoints.
17+
* [[[#transfer-protocol]]] and [[[#transfer-http]]] documents that define how [=Transfer Processes=] using a given data transfer protocol are governed via HTTPS endpoints.

0 commit comments

Comments
 (0)