Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Editorial Rework #184

Merged
merged 69 commits into from
Feb 6, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
69 commits
Select commit Hold shift + click to select a range
6d7441f
adjust wording in the readme and summary
sebbader-sap Dec 6, 2023
940ccea
adjust wording in the transfer process chapter
sebbader-sap Dec 6, 2023
01b29d7
fix the transfer protocol resources
sebbader-sap Dec 6, 2023
ace6dc9
keep shacl messages for dspace:code consistent also in the negotiatio…
sebbader-sap Dec 6, 2023
a14f98a
remove the unneeded message shape
sebbader-sap Dec 6, 2023
ead37b3
adjust the wording in the transfer protocol binding
sebbader-sap Dec 6, 2023
bf00fe1
revert data plane / control plane deletion
sebbader-sap Dec 14, 2023
0317fc4
resort terms and terminology statements
sebbader-sap Dec 15, 2023
7ba7331
Merge branch 'main' into editorial-rework
sebbader-sap Dec 15, 2023
0b6d369
resolve remaining conflicts
sebbader-sap Dec 15, 2023
25c8c88
aligning chapter title pattern
sebbader-sap Dec 15, 2023
b3fe884
fixing inconsistencies in the dcat:Catalog descriptions
sebbader-sap Dec 15, 2023
1383032
adjust wording in the readme and summary
sebbader-sap Dec 6, 2023
e918ace
adjust wording in the transfer process chapter
sebbader-sap Dec 6, 2023
38f8cf6
fix the transfer protocol resources
sebbader-sap Dec 6, 2023
5d22c4c
keep shacl messages for dspace:code consistent also in the negotiatio…
sebbader-sap Dec 6, 2023
d00c4d0
remove the unneeded message shape
sebbader-sap Dec 6, 2023
fd61549
adjust the wording in the transfer protocol binding
sebbader-sap Dec 6, 2023
79d27db
revert data plane / control plane deletion
sebbader-sap Dec 14, 2023
f42718c
resort terms and terminology statements
sebbader-sap Dec 15, 2023
983124a
resolve remaining conflicts
sebbader-sap Dec 15, 2023
1a396ed
aligning chapter title pattern
sebbader-sap Dec 15, 2023
f319459
fixing inconsistencies in the dcat:Catalog descriptions
sebbader-sap Dec 15, 2023
64cbbd8
Merge branch 'main' into editorial-rework
juliapampus Dec 17, 2023
c875c40
chore: add linkage for provider term
juliapampus Dec 17, 2023
3876aba
chore: add linkage for consumer term
juliapampus Dec 17, 2023
2b1fb07
chore: remove reference to OpenAPI spec
juliapampus Dec 17, 2023
cd38b31
fix missing attributes from catalog, dataset, distribution etc.
sebbader-sap Dec 19, 2023
898d0a7
Merge commit '2b1fb0729dbda98acc76c044b3cebe5be2de4746' into editoria…
sebbader-sap Dec 19, 2023
5c1be60
minor fixes in the negotiation section
sebbader-sap Dec 19, 2023
3f35bb0
chore: update terminology
juliapampus Dec 20, 2023
5eedd74
chore: cleanup protocol document (CN)
juliapampus Dec 20, 2023
0460c94
refactor: move .json files to example folders
juliapampus Jan 12, 2024
048971d
chore: align transfer terminology
juliapampus Jan 12, 2024
e852e0e
chore: clean up negotiation http binding
juliapampus Jan 16, 2024
7526282
docs: update README
juliapampus Jan 16, 2024
06f86ea
chore: restructure catalog procotol
juliapampus Jan 16, 2024
f4eb176
chore: update common .md files
juliapampus Jan 16, 2024
11fd5d4
chore(CN-binding): remove connector, add callback from/to URL
juliapampus Jan 17, 2024
bb1b75c
chore(CN): update response type description
juliapampus Jan 17, 2024
fd35609
chore: clean up catalog http binding
juliapampus Jan 17, 2024
0b347fd
chore: fix JSON snippets
juliapampus Jan 17, 2024
95a7366
chore: update formatting of model.md
juliapampus Jan 17, 2024
bc697df
chore: revert removing credential issuer
juliapampus Jan 17, 2024
023f86b
chore(CN): resolve leftover copy&paste mistakes
juliapampus Jan 17, 2024
6775195
chore: restructure transfer protocol document
juliapampus Jan 17, 2024
7427288
chore: move protocol figures to sub-folder
juliapampus Jan 17, 2024
d15113c
chore: clean up transfer http binding
juliapampus Jan 17, 2024
e5b3a51
chore: align documents
juliapampus Jan 17, 2024
3aa05e7
chore(catalog): change section hierarchy
juliapampus Jan 17, 2024
5dc3726
chore: add ToCs to protocol & binding documents
juliapampus Jan 17, 2024
7ea16c8
chore: update broken/missing links in list files
juliapampus Jan 17, 2024
fad75a6
chore(CN-termination): align type of `code` with spec documents
juliapampus Jan 17, 2024
4fd2c89
chore(CN): clean up diagram files
juliapampus Jan 17, 2024
e87eb2a
chore: update terminology.md
juliapampus Jan 17, 2024
2600b01
switch links for the catalog and dataset resources
sebbader-sap Jan 30, 2024
2b2b371
correct dcat:keyword in the catalog example
sebbader-sap Jan 30, 2024
1a7be68
replace UUID with "identifier" in model.md
sebbader-sap Jan 30, 2024
ba8d3a4
add example as the schema for the catalog example uuid
sebbader-sap Jan 30, 2024
815aedc
fix the dataset-request-message diagram
sebbader-sap Jan 30, 2024
11cb69e
Editorial rework merge (#2) (#209)
sebbader-sap Feb 1, 2024
f7f95ed
Merge commit 'e464d64f421a4e95abaeb45ab88991c8a80a3546' into editoria…
sebbader-sap Feb 1, 2024
498580b
fix typo in contract negotiation binding
sebbader-sap Feb 1, 2024
a6b51bc
revert changes to the release folder
sebbader-sap Feb 1, 2024
bbe23cd
add note on callback paths
sebbader-sap Feb 1, 2024
c45b400
chore: update broken ToCs
juliapampus Feb 6, 2024
51d42e4
chore: markdown inspection
juliapampus Feb 6, 2024
0e12152
fix: revert changes to release folder
juliapampus Dec 8, 2023
0e0f58c
chore: apply minor improvements
juliapampus Feb 6, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 21 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,19 @@

> __NOTE:__ These specifications are working drafts and subject to change.

> __NOTE:__ For GitHub users, The link to the rendered content is https://docs.internationaldataspaces.org/dataspace-protocol/
> __NOTE:__ For GitHub users, the link to the rendered content is https://docs.internationaldataspaces.org/dataspace-protocol/.

> __NOTE:__ The human-friendly version of this specification in the
> [IDSA Knowledge base](https://docs.internationaldataspaces.org/dataspace-protocol/)
> will always show the latest version of the document.
> The version history and changes are provided via the [GitHub Repository](https://github.com/International-Data-Spaces-Association/ids-specification/).
> __NOTE:__ The human-friendly version of this specification in the [IDSA Knowledge base](https://docs.internationaldataspaces.org/dataspace-protocol/) will always show the latest version of the document. The version history and changes are provided via the [GitHub Repository](https://github.com/International-Data-Spaces-Association/ids-specification/).

## About versions of the Dataspace Protocol

The specification of the Dataspace Protocol is work in progress and subject to change.
Since [version 0.8](https://github.com/International-Data-Spaces-Association/ids-specification/releases/tag/v0.8) the specification is stable with changes in details.
All changes made to the specification can be reviewed in the [GitHub repository](https://github.com/International-Data-Spaces-Association/ids-specification/).
The specification of the Dataspace Protocol is work in progress and subject to change. Since [version 0.8](https://github.com/International-Data-Spaces-Association/ids-specification/releases/tag/v0.8) the specification is stable with changes in details. All changes made to the specification can be reviewed in the [GitHub repository](https://github.com/International-Data-Spaces-Association/ids-specification/).

> __NOTE:__ A versioning scheme beside the commits to the repository is not available but will be provided in the future.

## Abstract

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](./model/terminology.md#agreement), and access data as part of a federation of technical systems termed a
[Dataspace](./model/terminology.md#dataspace).
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](./model/terminology.md#agreement), and access data as part of a federation of technical systems termed a [Dataspace](./model/terminology.md#dataspace).

## Introduction

Expand All @@ -30,42 +23,44 @@ The __Dataspace Protocol__ defines how this metadata is provisioned:

1. How [Datasets](./model/terminology.md#dataset) are deployed as [DCAT Catalogs](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) and usage control is expressed as [ODRL Policies](https://www.w3.org/TR/odrl-model/).
2. How [Agreements](./model/terminology.md#agreement) that govern data usage are syntactically expressed and electronically negotiated.
3. How [Datasets](./model/terminology.md#dataset) are accessed using Transfer Process Protocols.
3. How [Datasets](./model/terminology.md#dataset) are accessed using [Transfer Process Protocols](./model/terminology.md#transfer-process-protocol).

These specifications build on protocols located in the [ISO OSI model (ISO/IEC 7498-1:1994)](https://www.iso.org/standard/20269.html) layers, like HTTPS.
These specifications build 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](./model/terminology.md#dataspace).
On this foundation the binding to Transfer Process Protocols, like HTTPS, is described.
On this foundation the bindings to data transfer protocols, like HTTPS, are described.

The specifications are organized into the following documents:

* __*Dataspace Model*__ and __*Dataspace Terminology*__ documents that define key terms.
* __*Catalog Protocol*__ and __*Catalog HTTPS Binding*__ documents that define how [DCAT Catalogs](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) are published and accessed as HTTPS endpoints respectively.
* __*Contract Negotiation Protocol*__ and __*Contract Negotiation HTTPS Binding*__ documents that define how [Contract Negotiations](./model/terminology.md#contract-negotiation) are conducted and requested via HTTPS endpoints.
* __*Transfer Process Protocol*__ and __*Transfer Process HTTPS Binding*__ documents that define how [Transfer Processes](./model/terminology.md#transfer-process) using a given data transfer protocol are governed via HTTPS
* [__*Dataspace Model*__](./model/model.md) and [__*Dataspace Terminology*__](./model/terminology.md) documents that define key terms.
* [__*Common Functionalities*__](./common/common.protocol.md) and their [__*Binding in HTTPS*__](./common/common.binding.https.md) declares cross-cutting functions as, e.g., the declaration of supported versions of this Dataspace Protocol.
* [__*Catalog Protocol*__](./catalog/catalog.protocol.md) and [__*Catalog HTTPS Binding*__](./catalog/catalog.binding.https.md) documents that define how [DCAT Catalogs](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) are published and accessed as HTTPS endpoints respectively.
* [__*Contract Negotiation Protocol*__](./negotiation/contract.negotiation.protocol.md) and [__*Contract Negotiation HTTPS Binding*__](./negotiation/contract.negotiation.binding.https.md) documents that define how [Contract Negotiations](./model/terminology.md#contract-negotiation) are conducted and requested via HTTPS endpoints.
* [__*Transfer Process Protocol*__](./transfer/transfer.process.protocol.md) and [__*Transfer Process HTTPS Binding*__](./transfer/transfer.process.binding.https.md) documents that define how [Transfer Processes](./model/terminology.md#transfer-process) using a given data transfer protocol are governed via HTTPS
endpoints.

This specification does not cover the data transfer process as such.
While the data transfer is controlled by the __*Transfer Process Protocol*__ mentioned above, the data transfer itself and especially the handling of technical exceptions is an obligation to the Transport Protocol.
While the data transfer is controlled by the __*Transfer Process Protocol*__ mentioned above, e.g. the initation 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.
As an implication, the data transfer can be conducted in a separated process if required, as long as this process is to the specified extend controlled by the __*Transfer Process Protocol*__.


### Context of this specification

The __Dataspace Protocol__ is used in the context of [Dataspaces](./model/terminology.md#dataspace) 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](./model/terminology.md#participant) in [Dataspaces](./model/terminology.md#dataspace) and therefore the protocol specified here is required to join any [Dataspace](./model/terminology.md#dataspace).
Beyond the technical interoperability measures described in this specification, semantic interoperability should also be addressed by the [Participants](./model/terminology.md#participant). On the perspective of the [Dataspace](./model/terminology.md#dataspace), interoperability needs to be addressed also on the level of trust, on organizational level and on legal level.
The aspect of cross [Dataspace](./model/terminology.md#dataspace) communication is not subject of this document, as this is addressed by the [Dataspaces'](./model/terminology.md#dataspace) organizational and legal agreements.
In this context, the specification provides fundamental technical interoperability for [Participants](./model/terminology.md#participant) in [Dataspaces](./model/terminology.md#dataspace).
Beyond the technical interoperability measures described in this specification, semantic interoperability should also be addressed by the [Participants](./model/terminology.md#participant). On the perspective of the [Dataspace](./model/terminology.md#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'](./model/terminology.md#dataspace) organizational and legal agreements.

The interaction of [Participants](./model/terminology.md#participant) in a [Dataspace](./model/terminology.md#dataspace) is conducted by the [Participant Agents](./model/terminology.md#participant-agent), so-called [Connectors](./model/terminology.md#connector--data-service-), which implement the protocols described above.
While most interactions take place between [Connectors](./model/terminology.md#connector--data-service-), some interactions with other systems are required.
The figure below provides an overview on the context of this specification.

An [Identity Provider](./model/terminology.md#identity-provider) realizes the required interfaces and provides required information to implement Trust Framework of a [Dataspace](./model/terminology.md#dataspace).
The validation of the identity of a given [Participant Agent](./model/terminology.md#participant-agent) and the validation of additional claims is the fundamental mechanism. The structure and content of such claims and identity may vary between different [Dataspaces](./model/terminology.md#dataspace), as well as the structure of such an Identity Provider, e.g. a centralized system, a decentralized system or a federated system.
An [Identity Provider](./model/terminology.md#identity-provider) realizes the required interfaces and provides required information to implement the Trust Framework of a [Dataspace](./model/terminology.md#dataspace).
The validation of the identity of a given [Participant Agent](./model/terminology.md#participant-agent) and the validation of additional claims is a fundamental mechanism. The structure and content of such claims and identities may, however, vary between different [Dataspaces](./model/terminology.md#dataspace), as well as the structure of such an [Identity Provider](./model/terminology.md#identity-provider), e.g. a centralized system, a decentralized system or a federated system. Other specifications, like the Identity and Trust Protocol ([IATP](https://github.com/eclipse-tractusx/identity-trust)), define the respective functions.
mkollenstart marked this conversation as resolved.
Show resolved Hide resolved

A [Connector](./model/terminology.md#connector--data-service-) will implement additional internal functionalities, like monitoring or policy engines, as appropriate. It is not covered by this specification, if a [Connector](./model/terminology.md#connector--data-service-) implements such or how.
A [Connector](./model/terminology.md#connector--data-service-) will implement additional internal functionalities, like monitoring or policy engines, as appropriate. It is not covered by this specification if a [Connector](./model/terminology.md#connector--data-service-) implements such or how.

The same applies for the data, which is transferred between the systems. While this document does not define the transport protocol, the structure, syntax and semantics of the data, a specification for those aspects is required and subject to the agreements of the [Participants](./model/terminology.md#participant) or the [Dataspace](./model/terminology.md#dataspace).
The same applies for the actual data that is transferred between the systems. While this document does not define the transport protocol, the structure, syntax or semantics of the data, a specification for those aspects is required and subject to the agreements of the [Participants](./model/terminology.md#participant) or the [Dataspace](./model/terminology.md#dataspace).

![Overview on protocol and context](./resources/figures/ProtocolOverview.png)

Expand Down
5 changes: 5 additions & 0 deletions SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@
* [Terminology](./model/terminology.md)
* [Information Model](./model/model.md)

## Common Functionalities

* [Specification](./common/common.protocol.md)
* [Binding: HTTPS](./common/common.binding.https.md)

## Catalog

* [Specification](./catalog/catalog.protocol.md)
Expand Down
Loading