Skip to content

Commit

Permalink
Editorial Rework (#184)
Browse files Browse the repository at this point in the history 
* adjust wording in the readme and summary

* adjust wording in the transfer process chapter

* fix the transfer protocol resources

* keep shacl messages for dspace:code consistent also in the negotiation msgs

* remove the unneeded message shape

* adjust the wording in the transfer protocol binding

* revert data plane / control plane deletion

* resort terms and terminology statements

* resolve remaining conflicts

* aligning chapter title pattern

* fixing inconsistencies in the dcat:Catalog descriptions

* adjust wording in the readme and summary

* adjust wording in the transfer process chapter

* fix the transfer protocol resources

* keep shacl messages for dspace:code consistent also in the negotiation msgs

* remove the unneeded message shape

* adjust the wording in the transfer protocol binding

* revert data plane / control plane deletion

* resort terms and terminology statements

* resolve remaining conflicts

* aligning chapter title pattern

* fixing inconsistencies in the dcat:Catalog descriptions

* chore: add linkage for provider term

* chore: add linkage for consumer term

* chore: remove reference to OpenAPI spec

* fix missing attributes from catalog, dataset, distribution etc.

* minor fixes in the negotiation section

* chore: update terminology

* chore: cleanup protocol document (CN)

* refactor: move .json files to example folders

* chore: align transfer terminology

* chore: clean up negotiation http binding

* docs: update README

* chore: restructure catalog procotol

* chore: update common .md files

* chore(CN-binding): remove connector, add callback from/to URL

* chore(CN): update response type description

* chore: clean up catalog http binding

* chore: fix JSON snippets

* chore: update formatting of model.md

* chore: revert removing credential issuer

* chore(CN): resolve leftover copy&paste mistakes

* chore: restructure transfer protocol document

* chore: move protocol figures to sub-folder

* chore: clean up transfer http binding

* chore: align documents

* chore(catalog): change section hierarchy

* chore: add ToCs to protocol & binding documents

* chore: update broken/missing links in list files

* chore(CN-termination): align type of `code` with spec documents

* chore(CN): clean up diagram files

* chore: update terminology.md

* switch links for the catalog and dataset resources

* correct dcat:keyword in the catalog example

* replace UUID with "identifier" in model.md

* add example as the schema for the catalog example uuid

* fix the dataset-request-message diagram

* Editorial rework merge (#2) (#209)

* adding DCAT into JSON schema

* catalog schema DCAT fix

* fix catalog schema - DCAT

* fix catalog schema type error - DCAT

* DCAT catalog-shape added for Catalog class

* fix typo in DCAT of catalog schema

* fix type of dct:modified in DCAT of catalog schema

* DCAT dcat:CatalogRecord class added to catalog shape

* fix DCAT referecen in Resource catalog

* DCAT wrong property of Resource removed

* Fix DCAT catalog property of Resource

* ResourceShape added to catalog-shape.ttl

* RelationshipShape added to catalog-shape.ttl

* DCAT fix issue in skos:Concept

* DCAT ConceptShape ConceptSchemeShape and AgentShape added

* DCAT fix of Dataset property

* DCAT DatasetShape added

* DCAT DataServiceShape added

* DCAT Distribution catalog issue in type

* DCAT typo in property

* DCAT DataServiceShape added

* add references for reused classes & datatypes

* clean up on schema

* properties changed

* refactoring

* refactoring

* change dct:issued from string to dateTime

* fix dct:language from xsd:string to referencing a resource

* correcting hasPolicy declarations

* reviewing the catalog json schema

* refactor catalog json schema

* add odrl policy json schema

* fix syntax bugs in catalog json schema and adding foaf to the context.json

* fix bugs in catalog and contract json schemas

* fix examples to match to the catalog and contract json schemas

* replace relative reference to the contract-schema.json with an absolute url

* fix findings from mkollenstart's review

* testing negotiation-subtask-1.1 branch

* removing the test change

* unwnated characters

* Task #1: fix schemas and examples in "negotiation"

* correct references to GitHub raw files

* making 'required' field compatible to json 2019-09

* changes suggested by Sebastian

* changes to processId, correcting ref, removing Sec

* chnages since last review

* left over change

* missing s in dspace

* removing RightOperand property

* chnage in Permission, Json validated

* catalog subtask changes

* reverting dspace:filter type to object

* re-introducing updates to the json schemas

* fix filter in contract-request-message-schema

* fixing schema in "Transfer"

* Trying Shapes validation with Json-LD

* debugging catalog shapes

* fixing shapes in Catalog

* Negotiation Shapes validation

* Remove the ContractAgreement shape

* add the AgreementShape

* Negotiation shapes correction

* conflict merge

* schema and shapes re-validating after merge

* change assigner and assignee to string

* introduve verifiable credential structure to agreement msg

* adjust agreement msg example to vc pattern

* comment error

* Catalog shapes changes

* Shapes and schema validation for Transfer

* Introduce sh:IRI pattern for agreementId

* correction for dspace:reason and others

* dataset schema and puml

* Update catalog-error-schema.json - remove "dspace:code" and "dspace:reason" as mandatory

* Update dataset-schema.json - remove "dct:title" and "dct:description" as mandatory

* agreement verification change

* Transfer Messages - shapes and schema validation

* removing "@id" from transfer messages

* correction for catalog schema

* error handling

* pull request #11 changes

* pull request changes

* new chnages to editorial-rework

* merge editorial-rework to shapes-and-schemas

* fix last findings

---------

Co-authored-by: Thomas Ryborz <[email protected]>
Co-authored-by: tr-sap <[email protected]>
Co-authored-by: SimantVerma-Bcone <[email protected]>
Co-authored-by: simantvermasap <[email protected]>

* fix typo in contract negotiation binding

* revert changes to the release folder

* add note on callback paths

* chore: update broken ToCs

* chore: markdown inspection

* fix: revert changes to release folder

* chore: apply minor improvements

---------

Co-authored-by: Julia Pampus <[email protected]>
Co-authored-by: Thomas Ryborz <[email protected]>
Co-authored-by: tr-sap <[email protected]>
Co-authored-by: SimantVerma-Bcone <[email protected]>
Co-authored-by: simantvermasap <[email protected]>
  • Loading branch information
@sebbader-sap @juliapampus
@tr-sap @SimantVerma-Bcone @simantvermasap
6 people authored Feb 6, 2024
1 parent e464d64 commit b883a68
Show file tree
Hide file tree
Showing 99 changed files with 1,722 additions and 1,767 deletions.
47 changes: 21 additions & 26 deletions README.md
View file
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.

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
View file
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

0 comments on commit b883a68

Please sign in to comment.