chore: explain endpointType (#185)

* chore: explain endpointType

* chore: refactor profile definition

* fix: wording

Co-authored-by: Jim Marino <[email protected]>

* Update specifications/common/terminology.md

---------

Co-authored-by: Jim Marino <[email protected]>
Co-authored-by: Julia Pampus <[email protected]>

Author: 3 people

specifications/common/introduction.md

@@ -6,7 +6,7 @@ This specification builds on protocols located in the [ISO OSI model (ISO/IEC 74
 
 _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._
 
-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.
+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. However, not every standard-compliant class might be compliant to the [=Dataspace=] [=Profile=]. They are not separate artifacts but implicitly contained in the JSON schemas for the [=Message Types=] of this specification.
 
 This specification is organized into the following documents:
 

specifications/common/terminology.md

@@ -74,6 +74,10 @@ A technology system that performs operations and interactions in a [=Dataspace=]
 
 A set of rules, duties, and obligations that define the terms of use for a [=Dataset=].
 
+<dfn>Profile</dfn>
+
+A restriction or subset of a specification that enforces every occurrence of an externally defined class to be conformant with the original definition.
+
 <dfn>Provider</dfn>
 
 A [=Participant=] that offers a [=Dataset=].

specifications/transfer/transfer.process.protocol.md

@@ -101,12 +101,12 @@ The Transfer Request Message is sent by a [=Consumer=] to initiate a TP.
 - The `dct:format` property is a format specified by a `Distribution` for the [=Dataset=] associated with
   the [=Agreement=]. This is generally obtained from the [=Provider=]'s [=Catalog=].
 - The `dataAddress` property must only be provided if the `dct:format` requires a push transfer.
-- The `dataAddress` contains a transport-specific endpoint address for pushing the data. It may include a temporary
-  authorization via the `endpointProperties` property.
+- The `dataAddress` contains a transport-specific set of properties for pushing the data. It may include an `endpoint`, 
+  a temporary authorization via the `endpointProperties` property - depending on the `endpointType`.
 - `callbackAddress` is a URI indicating where messages to the [=Consumer=] should be sent. If the address is not
   understood, the [=Provider=] MUST return an UNRECOVERABLE error.
 
-- The `endpointProperties` may contain the following optional values:
+- The `endpointProperties` may (among others) contain the following optional values:
     - `authorization` - An opaque authorization token that clients must present when accessing the transport-specific
       endpoint address.
     - `authType` - The auth token type. For example, the value may be `bearer`. If present, this value may be used in
@@ -137,13 +137,13 @@ again, the [=Provider=] should respond with an appropriate [Transfer Start Messa
 The Transfer Start Message is sent by the [=Provider=] to indicate the data transfer has been initiated.
 
 - The `dataAddress` is only provided if the current transfer is a pull transfer and contains a transport-specific
-  endpoint address for obtaining the data. It may include a temporary authorization via the `endpointProperties`
-  property.
-- The `endpointProperties` may contain the following optional values:
-    - `authorization` - An opaque authorization token that clients must present when accessing the transport-specific
-      endpoint address.
-    - `authType` - The auth token type. For example, the value may be `bearer`. If present, this value may be used in
-      conjunction with transport rules to define how the client must present an authorization token.
+  endpoint address for obtaining the data. The kind of transport is signaled by the `endpointType` property which
+  determines a set of required `endpointProperties` in a [=Profile=] separate from this specification.
+- The `endpointProperties` may (among others) contain the following optional values:
+  - `authorization` - An opaque authorization token that clients must present when accessing the transport-specific
+    endpoint address.
+  - `authType` - The auth token type. For example, the value may be `bearer`. If present, this value may be used in
+    conjunction with transport rules to define how the client must present an authorization token.
 
 ### Transfer Suspension Message