chore: refactor transfer process description (#238)

* fix: resolve spelling mistake * chore: update TP process description and diagrams * chore: fix broken references * chore: add dataAddress to sequence diagrams * chore: apply feedback
International-Data-Spaces-Association · Feb 22, 2024 · 1f1bcca · 1f1bcca
1 parent b80e32d
commit 1f1bcca
Show file tree

Hide file tree

Showing 11 changed files with 98 additions and 94 deletions.
diff --git a/catalog/catalog.binding.https.md b/catalog/catalog.binding.https.md
@@ -52,7 +52,7 @@ Authorization: ...
 }
 ```
 
-- The `Authorization` header is optional if the [Catalog Service](../model/terminology.md#catalog-service) does not require authorization. If present, the contents of the `Authorization` header are detailed in the [Authorization section](#13-authorization).
+- The `Authorization` header is optional if the [Catalog Service](../model/terminology.md#catalog-service) does not require authorization. If present, the contents of the `Authorization` header are detailed in the [Authorization section](../common/common.binding.https.md#2-authorization).
 
 - The `filter` property is optional. If present, the `filter` property can contain an implementation-specific filter expression or query to be executed as part of the [Catalog](../model/terminology.md#catalog) request. If a filter expression is not supported by an implementation, it must return a HTTP 400 (Bad Request) response.
 
@@ -80,7 +80,7 @@ Authorization: ...
 }
 ```
 
-- The `Authorization` header is optional if the [Catalog Service](../model/terminology.md#catalog-service) does not require authorization. If present, the contents of the `Authorization` header are detailed in the [Authorization section](#13-authorization).
+- The `Authorization` header is optional if the [Catalog Service](../model/terminology.md#catalog-service) does not require authorization. If present, the contents of the `Authorization` header are detailed in the [Authorization section](../common/common.binding.https.md#2-authorization).
 
 ##### Response
 

diff --git a/catalog/catalog.protocol.md b/catalog/catalog.protocol.md
@@ -2,29 +2,29 @@
 
 This document outlines the [Catalog Protocol](../model/terminology.md#catalog-protocol). The used terms are described [here](../model/terminology.md).
 
-- [Catalog Protocol](#catalog-protocol)
-  - [1 Introduction](#1-introduction)
-    - [1.1 DCAT Vocabulary Mapping](#11-dcat-vocabulary-mapping)
-      - [1.1.1 Dataset](#111-dataset)
-        - [odrl:hasPolicy](#odrlhaspolicy)
-      - [1.1.2 Distributions](#112-distributions)
-      - [1.1.3 Data Service](#113-data-service)
-        - [dspace:dataServiceType](#dspacedataservicetype)
-        - [dcat:servesDataset](#dcatservesdataset)
-    - [1.2 DCAT and ODRL Profiles](#12-dcat-and-odrl-profiles)
-  - [2 Message Types](#2-message-types)
-    - [2.1 Catalog Request Message](#21-catalog-request-message)
-    - [2.2 Dataset Request Message](#22-dataset-request-message)
-  - [3 Response Types](#3-response-types)
-    - [3.1 ACK - Catalog](#31-ack---catalog)
-    - [3.2 ACK - Dataset](#32-ack---dataset)
-    - [3.3 ERROR - Catalog Error](#33-error---catalog-error)
-  - [4 Technical Considerations](#4-technical-considerations)
-    - [4.1 Queries and Filter Expressions](#41-queries-and-filter-expressions)
-    - [4.2 Replication Protocol](#42-replication-protocol)
-    - [4.3 Security](#43-security)
-      - [4.3.1 The Proof Metadata Endpoint](#431-the-proof-metadata-endpoint)
-    - [4.4 Catalog Brokers](#44-catalog-brokers)
+* [1 Introduction](#1-introduction)
+  * [1.1 DCAT Vocabulary Mapping](#11-dcat-vocabulary-mapping)
+    * [1.1.1 Dataset](#111-dataset)
+      * [odrl:hasPolicy](#odrl--haspolicy)
+    * [1.1.2 Distributions](#112-distributions)
+    * [1.1.3 Data Service](#113-data-service)
+      * [dspace:dataServiceType](#dspace--dataservicetype)
+      * [dcat:servesDataset](#dcat--servesdataset)
+    * [1.1.4 Participant Id](#114-participant-id)
+  * [1.2 DCAT and ODRL Profiles](#12-dcat-and-odrl-profiles)
+* [2 Message Types](#2-message-types)
+  * [2.1 Catalog Request Message](#21-catalog-request-message)
+  * [2.2 Dataset Request Message](#22-dataset-request-message)
+* [3 Response Types](#3-response-types)
+  * [3.1 ACK - Catalog](#31-ack---catalog)
+  * [3.2 ACK - Dataset](#32-ack---dataset)
+  * [3.3 ERROR - Catalog Error](#33-error---catalog-error)
+* [4 Technical Considerations](#4-technical-considerations)
+  * [4.1 Queries and Filter Expressions](#41-queries-and-filter-expressions)
+  * [4.2 Replication Protocol](#42-replication-protocol)
+  * [4.3 Security](#43-security)
+    * [4.3.1 The Proof Metadata Endpoint](#431-the-proof-metadata-endpoint)
+  * [4.4 Catalog Brokers](#44-catalog-brokers)
 
 ## 1 Introduction
 

diff --git a/catalog/message/example/catalog.json b/catalog/message/example/catalog.json
@@ -19,7 +19,7 @@
       "@id": "urn:uuid:4aa2dcc8-4d2d-569e-d634-8394a8834d77",
       "@type": "dcat:DataService",
       "dcat:endpointDescription": "dspace:connector",
-      "dcat:endpointURL": "https://provder-a.com/connector"
+      "dcat:endpointURL": "https://provider-a.com/connector"
     }
   ],
   "dcat:dataset": [
@@ -64,7 +64,7 @@
           {
             "@id": "urn:uuid:4aa2dcc8-4d2d-569e-d634-8394a8834d77",
             "@type": "dcat:DataService",
-            "dcat:endpointURL": "https://provder-a.com/connector"
+            "dcat:endpointURL": "https://provider-a.com/connector"
           }
         ]
       }

diff --git a/catalog/message/example/dataset.json b/catalog/message/example/dataset.json
@@ -37,7 +37,7 @@
       "dcat:accessService": [
         {
           "@id": "urn:uuid:4aa2dcc8-4d2d-569e-d634-8394a8834d77",
-          "dcat:endpointURL": "https://provder-a.com/connector"
+          "dcat:endpointURL": "https://provider-a.com/connector"
         }
       ]
     }

diff --git a/model/model.md b/model/model.md
@@ -21,7 +21,7 @@ The relationships between the primary [Dataspace](./terminology.md#dataspace) en
 Note that all relationships are multiplicities unless specified. `Dataspace Authority` and `Dataspace Registry` are non-normative entities.
 
 - A [Dataspace Authority](./terminology.md#dataspace-authority) manages one or more [Dataspaces](./terminology.md#dataspace). This will include [Participant](./terminology.md#participant) registration and may entail mandating business and/or technical requirements. For example, a [Dataspace Authority](./terminology.md#dataspace-authority) may require [Participants](./terminology.md#participant) to obtain some form of business certification. A [Dataspace Authority](./terminology.md#dataspace-authority) may also impose technical requirements such as support for the technical enforcement of specific usage policies.
-- A [Dataspace Registry](./terminology.md#dataspace-registration-service-dataspace-registry) records dataspace participants.
+- A [Dataspace Registry](./terminology.md#dataspace-registration-service--dataspace-registry-) records dataspace participants.
 - A [Participant](./terminology.md#participant) is a member of one or more [Dataspaces](./terminology.md#dataspace). A [Participant](./terminology.md#participant) registers [Participant Agents](./terminology.md#participant-agent) that perform tasks on its behalf.
 - A [Participant Agent](./terminology.md#participant-agent) performs tasks such as publishing a [Catalog](./terminology.md#catalog) or engaging in a [Transfer Process](./terminology.md#transfer-process). In order to accomplish these tasks, a [Participant Agent](./terminology.md#participant-agent) may use a _**verifiable presentation**_ generated from a _**credential**_ obtained from a third-party [Credential Issuer](./terminology.md#credential-issuer). A [Participant Agent](./terminology.md#participant-agent) may also use an _**ID token**_ issued by a third-party [Identity Provider](./terminology.md#identity-provider). Note that a [Participant Agent](./terminology.md#participant-agent) is a logical construct and does not necessarily correspond to a single runtime process.
 - An [Identity Provider](./terminology.md#identity-provider) is a trust anchor that generates `ID tokens` used to verify the identity of a [Participant Agent](./terminology.md#participant-agent). Multiple identity providers may operate in a [Dataspace](./terminology.md#dataspace). The types and semantics of ID tokens are not part of this specification. An [Identity Provider](./terminology.md#identity-provider) may be a third-party or a [Participant](./terminology.md#participant) itself (for example, in the case of decentralized identifiers).

diff --git a/releases/v0.8/catalog/message/catalog.json b/releases/v0.8/catalog/message/catalog.json
@@ -16,7 +16,7 @@
       "@id": "urn:uuid:4aa2dcc8-4d2d-569e-d634-8394a8834d77",
       "@type": "dcat:DataService",
       "dcat:endpointDescription": "dspace:connector",
-      "dcat:endpointURL": "https://provder-a.com/connector"
+      "dcat:endpointURL": "https://provider-a.com/connector"
     }
   ],
   "dcat:dataset": [

diff --git a/transfer/figures/pull-transfer-process.png b/transfer/figures/pull-transfer-process.png
diff --git a/transfer/figures/pull-transfer-process.puml b/transfer/figures/pull-transfer-process.puml
@@ -1,42 +1,42 @@
 @startuml "pull-transfer-process"
 !pragma layout smetana
 
-!include ../common/style/diagram.styles.puml
+!include ../../common/style/diagram.styles.puml
 
 hide empty description
 
 skinparam defaultTextAlignment center
 
 box Consumer
-participant DataPlane1
-participant ControlPlane1
+participant DataPlane_C
+participant ControlPlane_C
 end box
 
 box Provider
-participant ControlPlane2
-participant DataPlane2
+participant ControlPlane_P
+participant DataPlane_P
 end box
 
-activate ControlPlane1
-activate ControlPlane2
+activate ControlPlane_C
+activate ControlPlane_P
 
-ControlPlane1 -> ControlPlane2 : TransferRequestMessage
-ControlPlane2 --> ControlPlane1 : ACK
+ControlPlane_C -> ControlPlane_P : TransferRequestMessage
 
-ControlPlane2 -> ControlPlane1 : TransferStartMessage(dataAddress)
-ControlPlane1 --> ControlPlane2 : ACK
+ControlPlane_P -> ControlPlane_C : TransferStartMessage(dataAddress)
 
-activate DataPlane1
-DataPlane1 -> DataPlane2 : pullData
-activate DataPlane2
-DataPlane2 --> DataPlane1 : data
-deactivate DataPlane2
-deactivate DataPlane1
+activate DataPlane_C
+activate DataPlane_P
+DataPlane_C -> DataPlane_P : pull data
+deactivate DataPlane_P
+deactivate DataPlane_C
 
-ControlPlane1 -> ControlPlane2 : TransferCompletionMessage
-ControlPlane2 --> ControlPlane1 : ACK
+alt "Consumer ends TP"
+    ControlPlane_C -> ControlPlane_P : TransferCompletionMessage
+else "Provider ends TP"
+    ControlPlane_P -> ControlPlane_C : TransferCompletionMessage
+end
 
-deactivate ControlPlane1
-deactivate ControlPlane2
+deactivate ControlPlane_C
+deactivate ControlPlane_P
 
 @enduml
diff --git a/transfer/figures/push-transfer-process.png b/transfer/figures/push-transfer-process.png
diff --git a/transfer/figures/push-transfer-process.puml b/transfer/figures/push-transfer-process.puml
@@ -1,42 +1,38 @@
 @startuml "push-transfer-process"
 !pragma layout smetana
 
-!include ../common/style/diagram.styles.puml
+!include ../../common/style/diagram.styles.puml
 
 hide empty description
 
 skinparam defaultTextAlignment center
 
 box Consumer
-participant DataPlane1
-participant ControlPlane1
+participant DataPlane_C
+participant ControlPlane_C
 end box
 
 box Provider
-participant ControlPlane2
-participant DataPlane2
+participant ControlPlane_P
+participant DataPlane_P
 end box
 
-activate ControlPlane1
-activate ControlPlane2
+activate ControlPlane_C
+activate ControlPlane_P
 
-ControlPlane1 -> ControlPlane2 : TransferRequestMessage(dataAddress)
-ControlPlane2 --> ControlPlane1 : ACK
+ControlPlane_C -> ControlPlane_P : TransferRequestMessage(dataAddress)
 
-ControlPlane2 -> ControlPlane1 : TransferStartMessage
-ControlPlane1 --> ControlPlane2 : ACK
+ControlPlane_P -> ControlPlane_C : TransferStartMessage
 
-activate DataPlane2
-DataPlane2 -> DataPlane1 : pushData(data)
-activate DataPlane1
-DataPlane1 --> DataPlane2 : ACK
-deactivate DataPlane2
-deactivate DataPlane1
+activate DataPlane_C
+activate DataPlane_P
+DataPlane_P -> DataPlane_C : push data
+deactivate DataPlane_P
+deactivate DataPlane_C
 
-ControlPlane2 -> ControlPlane1 : TransferCompletionMessage
-ControlPlane1 --> ControlPlane2 : ACK
+ControlPlane_P -> ControlPlane_C : TransferCompletionMessage
 
-deactivate ControlPlane1
-deactivate ControlPlane2
+deactivate ControlPlane_C
+deactivate ControlPlane_P
 
-@enduml
+@enduml