refactor: clean up (#62)

* refactor: cleanup

* refactor: remove comment

* fix: rename producer to provider

* fix: adapt name of landing page for GitBooks

Author: juliapampus

SUMMARY.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-* [Introduction](./README.md)
+* [Dataspace Protocol v0.8](./README.md)
 * [Terminology](./model/terminology.md)
 * [Information Model](./model/model.md)
 

catalog/catalog.binding.https.md

@@ -50,14 +50,14 @@ request.
 
 #### 2.3.2 OK (200) Response
 
-If the request is successful, the catalog service must return a response body containing a [Catalog](./message/catalog.json) which is a profiled DCAT Catalog type
+If the request is successful, the catalog service must return a response body containing a [Catalog](./message/catalog.json) which is a profiled DCAT `Catalog` type
 described by the [Catalog Protocol Specification](catalog.protocol.md).
 
 ### 2.4 The `catalog/datasets/{id}` endpoint
 
 #### 2.3.1 GET
 
-The [DatasetRequestMessage](catalog.protocol.md#21-datasetrequestmessage) corresponds to `GET https://<base>/catalog/datasets/{id}}`:
+The [DatasetRequestMessage](catalog.protocol.md#24-datasetrequestmessage) corresponds to `GET https://<base>/catalog/datasets/{id}}`:
 
 ```
 GET https://provider.com/datasets/{id}
@@ -71,7 +71,7 @@ The `Authorization` header is optional if the catalog service does not require a
 
 #### 2.4.2 OK (200) Response
 
-If the request is successful, the catalog service must return a response body containing a [Dataset](./message/dataset.json) which is a DCAT Dataset type
+If the request is successful, the catalog service must return a response body containing a [Dataset](./message/dataset.json) which is a DCAT `Dataset` type
 described by the [Catalog Protocol Specification](catalog.protocol.md).
 
 ## 3 Technical Considerations
@@ -147,5 +147,5 @@ Authorization: ...
 }
 ```
 
-The `CatalogResponseMessage` would be POSTed back to the endpoint. the response message could be posted mutiple times for paginated results and would need to include the
+The `CatalogResponseMessage` would be POSTed back to the endpoint. the response message could be posted multiple times for paginated results and would need to include the
 original `@id` value as a `correlationId` and a property indicating if the contents are complete (or additional responses will be sent).

catalog/catalog.protocol.md

@@ -59,7 +59,7 @@ be defined in the relevant catalog binding specification.
 The catalog contains all [Asset Entries](#31-asset-entry) which the requester shall see.
 
 
-### 2.3 Catalog Error Message
+### 2.3 CatalogErrorMessage
 
 ![](./message/diagram/catalog-error-message.png)
 
@@ -73,7 +73,7 @@ The catalog contains all [Asset Entries](#31-asset-entry) which the requester sh
 
 #### Description
 
-A Catalog Error Message is used when an error occured after a CatalogRequestMessage and the provider can not provide its catalog to the requester.
+A Catalog Error Message is used when an error occurred after a `CatalogRequestMessage` and the provider can not provide its catalog to the requester.
 
 ### 2.4 DatasetRequestMessage
 
@@ -115,10 +115,10 @@ target attributes. The target of an offer is the asset associated with the conta
 An asset may contain 0..N [DCAT Distributions](https://www.w3.org/TR/vocab-dcat-3/#Class:Distribution). Each distribution must have at least one `DataService` which specifies where
 the distribution is obtained. Specifically, a `DataService` specifies the endpoint for initiating a `ContractNegotiation` and `AssetTransfer`.
 
-A Distribution may have 0..N `hasPolicy` attributes that contain an ODRL `Offer` defining the usage control policy associated with the asset and this explicit Distribution.
+A Distribution may have 0..N `hasPolicy` attributes that contain an ODRL `Offer` defining the usage control policy associated with the asset and this explicit `Distribution`.
 Offers must NOT contain any target attributes. The target of an offer is the asset entry that contains the distribution.
 
-Support for `hasPolicy` attributes on a Distribution is optional. Implementations may choose not to support this feature, in which case they should return an appropriate error
+Support for `hasPolicy` attributes on a `Distribution` is optional. Implementations may choose not to support this feature, in which case they should return an appropriate error
 message to clients.
 
 ### 3.3 DataService

negotiation/contract.negotiation.binding.https.md

@@ -15,7 +15,7 @@ The OpenAPI definitions for this specification can be accessed [here](TBD).
 
 2. All request and response messages must use the `application/json` media type.
 
-### 2.2 ContractNegotiationError
+### 2.2 Contract Negotiation Error
 
 In the event of a client request error, the connector must return an appropriate HTTP 4xxx client error code. If an error body is returned it must be
 a [ContractNegotiationError](./message/contract-negotiation-error.json) with the following properties:
@@ -29,7 +29,7 @@ a [ContractNegotiationError](./message/contract-negotiation-error.json) with the
 ### 2.2.1 State transition errors
 
 If a client or provider connector makes a request that results in an invalid contract negotiation state transition as defined by the Contract Negotiation Protocol, it must return
-an HTTP code 400 (Bad Request) with an NegotiationErrorMessage in the response body.
+an HTTP code 400 (Bad Request) with an `ContractNegotiationError` in the response body.
 
 ### 2.3 Authorization
 
@@ -146,7 +146,7 @@ A consumer connector can POST a [ContractNegotiationEventMessage](./message/cont
 provider contract offer. If the negotiation state is successfully transitioned, the provider must return HTTP code 200 (OK). The response body is not specified and clients are not
 required to process it.
 
-If the current contract offer was created by the consumer, the provider must return HTTP code 400 (Bad Request) with an NegotiationErrorMessage in the response body.
+If the current contract offer was created by the consumer, the provider must return HTTP code 400 (Bad Request) with an `NegotiationErrorMessage` in the response body.
 
 ### 2.8 The provider `negotiations/:id/agreement/verification` resource
 

negotiation/contract.negotiation.protocol.md

@@ -32,12 +32,12 @@ The CN states are:
 
 ### Contract Negotiation State Machine
 
-The CN state machine is represented in the following diagram. Note that transitions to the TERMINATED state may occur from any other state and are not shown for simplicity:
+The CN state machine is represented in the following diagram. Note that transitions to the `TERMINATED` state may occur from any other state and are not shown for simplicity:
 
 ![](./contract.negotiation.state.machine.png)
 
 Transitions marked with `C` indicate a message sent by the consumer, transitions marked with `P` indicate a provider message. Terminal states are final; the state machine may
-not transition to another state. A new CN may be initiated if, for instance, the CN entered the TERMINATED state due to a network issue.
+not transition to another state. A new CN may be initiated if, for instance, the CN entered the `TERMINATED` state due to a network issue.
 
 ## Message Types
 
@@ -69,7 +69,7 @@ The CN state machine is transitioned upon receipt and acknowledgement of a messa
 
 #### Description
 
-The _ContractRequestMessage_ is sent by a consumer to initiate a contract negotiation.
+The `ContractRequestMessage` is sent by a consumer to initiate a contract negotiation.
 
 #### Notes
 
@@ -81,8 +81,6 @@ The _ContractRequestMessage_ is sent by a consumer to initiate a contract negoti
 
 - The dataset id is not technically required but included to avoid an error where the offer is associated with a different data set.
 
-> Comment sba (20.12.2022): Let's use the `offer.target` property for this, and nothing else.
-
 - `callbackAddress` is a URL indicating where messages to the consumer should be sent in asynchronous settings. If the address is not understood, the provider MUST return an
   UNRECOVERABLE error.
 
@@ -103,7 +101,7 @@ The _ContractRequestMessage_ is sent by a consumer to initiate a contract negoti
 
 #### Description
 
-The _ContractOfferMessage_ is sent by a provider to initiate a contract negotiation.
+The `ContractOfferMessage` is sent by a provider to initiate a contract negotiation.
 
 
 ### 3. ContractAgreementMessage
@@ -122,11 +120,11 @@ The _ContractOfferMessage_ is sent by a provider to initiate a contract negotiat
 
 #### Description
 
-The _ContractAgreementMessage_ is sent by a provider when it agrees to a contract. It contains the complete contract agreement with the provider's signature.
+The `ContractAgreementMessage` is sent by a provider when it agrees to a contract. It contains the complete contract agreement with the provider's signature.
 
-A _ContractAgreementMessage_ must contain a `processId`.
+A `ContractAgreementMessage` must contain a `processId`.
 
-A _ContractAgreementMessage_ must contain an ODRL Agreement.
+A `ContractAgreementMessage` must contain an ODRL `Agreement`.
 
 ### 4. ContractAgreementVerificationMessage
 
@@ -145,10 +143,10 @@ A _ContractAgreementMessage_ must contain an ODRL Agreement.
 
 #### Description
 
-The _ContractAgreementVerificationMessage_ is sent by a consumer to verify the acceptance of a contract agreement. A provider responds with an error if the signature can't be
+The `ContractAgreementVerificationMessage` is sent by a consumer to verify the acceptance of a contract agreement. A provider responds with an error if the signature can't be
 validated or is incorrect.
 
-A _ContractAgreementVerificationMessage_ must contain a `processId`.
+A `ContractAgreementVerificationMessage` must contain a `processId`.
 
 ### 5. ContractNegotiationEventMessage
 
@@ -167,15 +165,15 @@ A _ContractAgreementVerificationMessage_ must contain a `processId`.
 
 #### Description
 
-When the _ContractNegotiationEventMessage_ is sent by a provider with an `eventType` property set to `FINALIZED`, a contract agreement has been finalized and the associated asset
-is accessible. The state machine is transitioned to the PROVIDER_FINALIZED state. Other event types may be defined in the future. A consumer responds with an error if the signature
+When the `ContractNegotiationEventMessage` is sent by a provider with an `eventType` property set to `FINALIZED`, a contract agreement has been finalized and the associated asset
+is accessible. The state machine is transitioned to the `PROVIDER_FINALIZED` state. Other event types may be defined in the future. A consumer responds with an error if the signature
 can't be validated or is incorrect.
 
-It is an error for a consumer to send a ContractNegotiationEventMessage with an eventType `finalized` to the provider.
+It is an error for a consumer to send a `ContractNegotiationEventMessage` with an eventType `finalized` to the provider.
 
-When the _ContractNegotiationEventMessage_ is sent by a consumer with an `eventType` set to  `ACCEPTED`, the state machine is placed in the CONSUMER_AGREED state.
+When the `ContractNegotiationEventMessage` is sent by a consumer with an `eventType` set to  `ACCEPTED`, the state machine is placed in the `CONSUMER_AGREED` state.
 
-It is an error for a provider to send a ContractNegotiationEventMessage with an eventType `ACCEPTED` to the consumer.
+It is an error for a provider to send a `ContractNegotiationEventMessage` with an eventType `ACCEPTED` to the consumer.
 
 Note that contract events are not intended for propagation of agreement state after a contract negotiation has entered a terminal state. It is considered an error for a consumer or
 provider to send a contract negotiation event after the negotiation state machine has entered a terminal state.
@@ -194,15 +192,15 @@ provider to send a contract negotiation event after the negotiation state machin
 
 #### Description
 
-The _ContractNegotiationTerminationMessage_ is sent by a consumer or provider indicating it has cancelled the negotiation sequence. The message can be sent at any state of a negotiation
+The `ContractNegotiationTerminationMessage` is sent by a consumer or provider indicating it has cancelled the negotiation sequence. The message can be sent at any state of a negotiation
 without providing an explanation. Nevertheless, the sender may provide a description to help the receiver.
 
 #### Notes
 
 - A contract negotiation may be terminated for a variety of reasons, for example, an unrecoverable error was encountered or one of the parties no longer wishes to continue. A
   connector's operator may remove terminated contract negotiation resources after it has reached the terminated state.
 
-- If an error is received in response to a ContractNegotiationTerminationMessage, the sending party may choose to ignore the error.
+- If an error is received in response to a `ContractNegotiationTerminationMessage`, the sending party may choose to ignore the error.
 
 ## ContractNegotiationError
 
@@ -216,11 +214,11 @@ without providing an explanation. Nevertheless, the sender may provide a descrip
 
 #### Description
 
-The _ContractNegotiationError_ is an object returned by a consumer or provider indicating an error has occurred. It does not cause a state transition.
+The `ContractNegotiationError` is an object returned by a consumer or provider indicating an error has occurred. It does not cause a state transition.
 
 #### Notes
 
-- A _ContractNegotiationError_ is different to an error response. A _ContractNegotiationError_ does not necessarily finish the negotiation but can continue
+- A `ContractNegotiationError` is different to an error response. A `ContractNegotiationError` does not necessarily finish the negotiation but can continue
   afterwards.
 
 ## Hash and Signature Calculations
@@ -237,7 +235,7 @@ Hash and Signatures are calculated as defined in the [[JWS/CT]](#references) of
 
 - Adopt JWS/CT, an extension to the JSON Web Signature (JWS) standard.
 - Combines the detached mode of JWS with the JSON Canonicalization Scheme (JCS). Detached mode is when the payload section of the JWS is replaced
-  by an empty string:  XXXX.PAYLOAD.YYYY becomes XXXX..YYYY. Detached mode is described in the JWS spec.
+  by an empty string: `XXXX.PAYLOAD.YYYY` becomes `XXXX..YYYY`. Detached mode is described in the JWS spec.
 - Maintains Signed JSON data in JSON format.
 
 

negotiation/contract.negotiation.state.machine.puml

@@ -1,7 +1,7 @@
 @startuml "hub-request-processing"
 !pragma layout smetana
 
-!include ../diagrams/diagram.styles.puml
+!include ../common/style/diagram.styles.puml
 
 hide empty description
 

transfer/transfer-process-state-machine.puml

@@ -1,7 +1,7 @@
 @startuml "transfer-process-state-machine"
 !pragma layout smetana
 
-!include ../../diagrams/diagram.styles.puml
+!include ../common/style/diagram.styles.puml
 
 hide empty description
 

transfer/transfer.process.binding.https.md

@@ -119,7 +119,7 @@ Note that if the location header is not an absolute URL, it must resolve to an a
 #### 2.6.1 POST
 
 The consumer connector can POST a [TransferStartMessage](./message/transfer-start-message.json) to attempt to start a transfer process after it has been suspended. If the transfer
-process state is successfully transitioned, the producer must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.
+process state is successfully transitioned, the provider must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.
 
 ### 2.7 The provider `transfers/:id/completion` resource
 
@@ -140,7 +140,7 @@ process state is successfully transitioned, the provider must return HTTP code 2
 #### 2.9.1 POST
 
 The consumer connector can POST a [TransferSuspensionMessage](./message/transfer-suspension-message.json) to suspend a transfer process. If the transfer
-process state is successfully transitioned, the producer must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.
+process state is successfully transitioned, the provider must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.
 
 ## 3 Consumer Callback Path Bindings