Merging Q2 2022 release (#32)

* Merging Q2 2022 release

Merging Q2/2022 release from IDS-G pre

* Rename glossary/README.md to Glossary/README.md

* Update README.md

* Update CHANGELOG.md

* Update CHANGELOG.md

typo

CHANGELOG.md

@@ -1,17 +1,26 @@
 # Changelog
 All notable changes to this project will be documented in this file.
+
+=======
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [Q2/2022]
 
 ### Added
+- Clearing House Specification
 - Connector interaction, IDS-REST, IDSCP
+- New Label `open for discussion`
+- Usage Control terms, including contracts and examples
 
 ### Changed
-- none
-- 
+- DAPS: adding examples
+- DAPS: fixed typos and formatting
+- DAPS: aligned wth IDS Infomodel
+- Glossary: fixed typos, links and formatting
+- General: fixed tyos, broken links and formatting
+
 ### Removed
 - none
 
@@ -50,3 +59,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 - none
+

CONTRIBUTING.md

@@ -36,6 +36,7 @@ There are two types of labels: one describes the content of the issue and should
 developer that creates the issue. The other one, starting with `status`, will be added from the
 developer that takes on the issue. New issues should be initially marked with `status:open`.
 *  Basic labels: `bug`, `enhancement`, `suggestion`, `documentation` `outdated`, `question`, `discussion`
+*  `open for discussion`: issue is addressed but further contribution is requested by everyone
 *  `status:closed`: issue is closed (after successful approval by issuer and QA)
 *  `status:duplicate`: issue is a duplicate of another linked issue and therefore discontinued
 *  `status:in-progress`: issue has been assigned and is currently being worked on

Communication/Message-Structure/README.md

@@ -0,0 +1,60 @@
+# Message Structure/Format
+
+<a name="Message"></a>
+## ids:Message properties
+
+Core [ids:Message class](https://github.com/International-Data-Spaces-Association/InformationModel/blob/v4.1.0/model/communication/Message.ttl) with its properties, which are applicable to all messages.
+
+|  Properties /Fields | Description |
+|---|---|
+| modelVersion*  | Information Model version, against which the Message should be interpreted.  |
+| issued*  | Date of issuing the message. Value: Datetime in XML datetime pattern:  YYYY-MM-DDThh:mm:ss  |
+| correlationMessage  | Correlated message, e.g., response to a previous message. Value: URI of the correlatedMessage  |
+| issuerConnector*  | Origin Connector of the message. Value: URI of origin Connector  |
+| recipientConnector†  | Target Connector. Value: URI of target Connector  |
+| senderAgent*  | Agent, which initiated the message. Value: URI of an instance of ids:Agent.  |
+| recipientAgent†  | Agent, for which the message is intended. Value: URI of an instance of ids:Agent  |
+| securityToken*  | Token representing a claim, that the sender supports a certain security profile. Value: Instance of ids:DynamicAttributeToken.  |
+| authorizationToken  | An authorization token. The token can be issued from the Connector of the Data Provider (A) to the Connector of the Data Consumer (B). Can be used to avoid full authentication via DAPS, if Connector B wants to access the data of Connector A. Value: Instance of ids:Token  |
+| transferContract  | Contract which is (or will be) the legal basis of the data transfer. Value: Instance of class ids:Contract.  |
+| contentVersion  | Value describing the version of the content. Value: Version number of the content.  |
+
+\* -> Mandatory Property
+
+† -> Can have multiple values at the same time
+
+
+## Self-Description
+The Connector self-description is a serialized instantiation of the Connector class (ids:Connector) as defined by the IDS Information Model. The Connector self-description provides information about the Connector, as well as the catalog of Resources that are provided or requested by the Connector. A full explanation of what Resources are and how they are defined in the IDS is beyond the scope of this document. The IDS-RAM contains detailed information about this. In summary, the provided catalog of Resources, which are part of the Connector self-description, contain serialized instances of the Information Model class ids:Resource. Resources are units of information that embody a Digital Content (superclass ids:DigitalContent). Instances of ids:Resource contain metadata about the actual content and may also contain references to interfaces and representations. Interfaces (class ids:Interface) define operations that are supported by a Resource. Representations (class ids:Representation) further describe a Resource with, i.e., a particular media type or a specific data schema the data is based on. Note that Resources can have several Representations. The materialized Representations are called Artifacts (class ids:Artifact). Artifacts are served by Endpoints (class ids:Endpoint).
+
+
+
+A Connector has following properties, which are used for it's self-description.
+
+
+|Property |	Description |
+| ------------- |:-------------|
+|title†	|Connector title|
+|description†	|Connector description|
+|maintainer*	|Maintainer of the Connector. Value is an instance of class ids:Participant with an associated ID|
+|curator*	|Participant responsible for the correctness of the offered content.  Value is an instance of class ids:Participant with an associated ID|
+|outboundModelVersion*	|Information Model version being produced by the Connector|
+|inboundModelVersion*†	|Information Model version that the Connector is capable of reading/processing|
+|host†	|Network host of the Connector capable of serving / consuming Digital Contents and services|
+|defaultHost	|Default host that should be used for basic infrastructure interactions, e.g., providing the self description|
+|authInfo	|Information of the authentication service used by the Connector (e.g., to access a Connector’s data)|
+|securityProfile |Set of security guarantees claimed by a Connector. Value contains one of the default security profile codes, such as idsc:BASE_CONNECTOR_SECURITY_PROFILE. All profiles can be found here: https://github.com/International-Data-Spaces-Association/InformationModel/blob/develop/codes/SecurityGuarantee.ttl Valid attributes are: idsc:BASE_SECURITY_PROFILE idsc:TRUST_SECURITY_PROFILE idsc:TRUST_PLUS_SECURITY_PROFILE|
+|extendedGuarantee	|Reference to additional security guarantees that, if used in combination with a security profile instance, overrides the respective guarantee of the given predefined instance. Value is a pre-defined code for the claimed guarante, e.g., ids:USAGE_CONTROL_POLICY_ENFORCEMENT|
+|transportCertSha256†	|SHA256 fingerprints of currently valid transport certificates|
+|componentCertification	|Certification issued for the given Connector. Value is an instance of class ids:ComponentCertification|
+|publicKey	|Public Key that has been created for the Connector|
+|catalog	|Catalog of published / requested Resources. Value is a list of requested / offered ids:Resource instances|
+|physicalLocation |Physical location of the Connector. Value is an instance of any of the subclasses of ids:Location. ids:GeoPoint, ids:GeoFeature, or ids:BoundingPolygon. |
+|lifeCicleActivity† |Activity that occurs during the lifecycle of the Connector. Value is in instance of ids:Activity |
+
+\*  -> mandatory fields,
+
+† -> fields that can have multiple values at the same time
+
+
+The GitHub repository of the IDS Information Model contains a minimal working example of a Connector’s self-description ([RDF/TTL](https://github.com/International-Data-Spaces-Association/InformationModel/blob/develop/examples/TRUSTED_CONNECTOR.ttl) / [JSON-LD](https://github.com/International-Data-Spaces-Association/InformationModel/blob/develop/examples/TRUSTED_CONNECTOR.jsonld)). There is also an example of ids:Resource instance ([RDF/TTL](https://github.com/International-Data-Spaces-Association/InformationModel/blob/develop/examples/TEXT_RESOURCE.ttl), [JSON_LD](https://github.com/International-Data-Spaces-Association/InformationModel/blob/develop/examples/TEXT_RESOURCE.jsonld)). Both examples are available in RDF/Turtle and JSON-LD serialization.

Communication/Message-Types/README.md

@@ -0,0 +1,204 @@
+# Message Types
+
+## Message subtypes relevant for [Connector to Connector communication](../sequence-diagrams/data-connector-to-data-connector#message-flows-for-connector-to-connector-communication)
+
+There are three Subclasses of the abstract [ids:Message](../Message-Structure/README.md#idsmessage-properties) class. Namely the [ids:RequestMessage](#RequestMessage), [ids:ResponseMessage](#ResponseMessage) and [ids:NotificationMessage](#NotificationMessage). Each subclass itself has subclasses that fulfill a specific purpose in the communication process.
+
+For communication in the IDS, usually the more specific subclasses of the three mentioned ones are used. The message classes relevant for the Connector to Connector communication are listed below. The entire Collection of Messages available in the Information Model can be found [here](https://github.com/International-Data-Spaces-Association/InformationModel/blob/v4.1.0/taxonomies/Message.ttl).
+
+<a name="RequestMessage"></a>
+### ids:RequestMessage
+
+Client-generated message initiating a communication, motivated by a certain reason and with an answer expected.
+
+#### ids:DescriptionRequestMessage
+Message requesting metadata. If no URI is supplied via the ids:requestedElement field, this messages is treated like a self-description request and the recipient should return its self-description via an ids:DescriptionResponseMessage. However, if a URI is supplied, the Connector should either return metadata about the requested element via an ids:DescriptionResponseMessage, or send an ids:RejectionMessage, e.g., because the element was not found
+
+*Parent:* [ids:RequestMessage](#RequestMessage)
+
+*Additional Message Properties:*
+
+|  Properties /Fields | Description |
+|---|---|
+| requestedElement  | The element whose metadata is requested.  |
+
+*Implementations:*
+
+|  List of Implementations |
+|---|
+| [IDS-REST](../protocols/ids-rest/README.md#RequestMessage) |
+| [idscp2](../protocols/idscp2/ApplicationLayer/README.md) |
+| [multipart](../protocols/multipart#2-structure-of-a-multipart-message) |
+
+#### ids:ArtifactRequestMessage
+Message asking for retrieving the specified Artifact inside an ArtifactResponse message.
+
+*Parent:* [ids:RequestMessage](#RequestMessage)
+
+*Additional Message Properties:*
+
+|  Properties /Fields | Description |
+|---|---|
+| requestedArtifact*  | References an ids:Artifact.  |
+
+*Implementations:*
+
+|  List of Implementations |
+|---|
+| [IDS-REST](../protocols/ids-rest/README.md#ArtifactRequestMessage) |
+| [idscp2](../protocols/idscp2/ApplicationLayer/README.md) |
+| [multipart](../protocols/multipart#2-structure-of-a-multipart-message) |
+
+#### ids:ContractRequestMessage
+Message containing a suggested content contract (as offered by the data consumer to the data provider)(which is an instance of ids:ContractRequest).
+
+*Parent:* [ids:RequestMessage](#RequestMessage)
+
+*Additional Message Properties:*
+None
+
+*Implementations:*
+
+|  List of Implementations |
+|---|
+| [IDS-REST](../protocols/ids-rest/README.md#ContractRequestMessage) |
+| [idscp2](../protocols/idscp2/ApplicationLayer/README.md) |
+| [multipart](../protocols/multipart#2-structure-of-a-multipart-message) |
+
+<a name="ResponseMessage"></a>
+### ids:ResponseMessage
+
+Response messages hold information about the reaction of a recipient to a formerly sent command or event. They must be correlated to this message.
+
+#### ids:DescriptionResponseMessage
+Message containing the metadata, which a Connector previously requested via the ids:DescriptionRequestMessage.
+
+*Parent:* [ids:ResponseMessage](#ResponseMessage)
+
+*Additional Message Properties:*
+None
+
+*Implementations:*
+
+|  List of Implementations |
+|---|
+| [IDS-REST](../protocols/ids-rest/README.md#DescriptionResponseMessage) |
+| [idscp2](../protocols/idscp2/ApplicationLayer/README.md) |
+| [multipart](../protocols/multipart#2-structure-of-a-multipart-message) |
+
+#### ids:ArtifactResponseMessage
+Message that follows up a ArtifactRequestMessage and contains the Artifact's data.
+
+*Parent:* [ids:ResponseMessage](#ResponseMessage)
+
+*Additional Message Properties:*
+None
+
+*Implementations:*
+
+|  List of Implementations |
+|---|
+| [IDS-REST](../protocols/ids-rest/README.md#ArtifactResponseMessage) |
+| [idscp2](../protocols/idscp2/ApplicationLayer/README.md) |
+| [multipart](../protocols/multipart#2-structure-of-a-multipart-message) |
+
+#### ids:ContractAgreementMessage
+Message containing a contract, as an instance of ids:ContractAgreement, with resource access modalities on which two parties have agreed.
+
+*Parent:* [ids:ResponseMessage](#ResponseMessage)
+
+*Additional Message Properties:*
+None
+
+*Implementations:*
+
+|  List of Implementations |
+|---|
+| [IDS-REST](../protocols/ids-rest/README.md#ContractAgreementMessage) |
+| [idscp2](../protocols/idscp2/ApplicationLayer/README.md) |
+| [multipart](../protocols/multipart#2-structure-of-a-multipart-message) |
+
+#### ids:RejectionMessage
+Rejection messages are specialized response messages that notify the sender of a message that processing of this message has failed.
+
+*Parent:* [ids:ResponseMessage](#ResponseMessage)
+
+*Additional Message Properties:*
+
+|  Properties /Fields | Description |
+|---|---|
+| RejectionReason  | Code describing the Rejection Reason, e.g., idsc:NOT_FOUND. (see ids:RejectionReason class)  |
+
+*Implementations:*
+
+|  List of Implementations |
+|---|
+| [IDS-REST](../protocols/ids-rest/README.md#RejectionMessage) |
+| [idscp2](../protocols/idscp2/ApplicationLayer/README.md) |
+| [multipart](../protocols/multipart#2-structure-of-a-multipart-message) |
+
+#### ids:ContractRejectionMessage
+Message indicating rejection of a contract.
+
+*Parent:* [ids:ResponseMessage](#ResponseMessage)
+
+*Additional Message Properties:*
+
+|  Properties /Fields | Description |
+|---|---|
+| contractRejectionReason  | Human-readable text describing the reason for contract rejection  |
+
+*Implementations:*
+
+|  List of Implementations |
+|---|
+| [IDS-REST](../protocols/ids-rest/README.md#ContractRejectionMessage) |
+| [idscp2](../protocols/idscp2/ApplicationLayer/README.md) |
+| [multipart](../protocols/multipart#2-structure-of-a-multipart-message) |
+
+<a name="NotificationMessage"></a>
+### ids:NotificationMessage
+
+Event messages are informative and no response is expected by the sender.
+
+#### ids:ContractOfferMessage
+Message containing a offered content contract in the associated payload (which is an instance of ContractOffer).
+
+*Parent:* [ids:NotificationMessage](#NotificationMessage)
+
+*Additional Message Properties:*
+None
+
+*Implementations:*
+
+|  List of Implementations |
+|---|
+| [IDS-REST](../protocols/ids-rest/README.md#ContractOfferMessage) |
+| [idscp2](../protocols/idscp2/ApplicationLayer/README.md) |
+| [multipart](../protocols/multipart#2-structure-of-a-multipart-message) |
+
+#### ids:MessageProcessedNotificationMessage
+Notification that a message has been successfully processed (i.e., not ignored or rejected).
+
+*Parent:* [ids:NotificationMessage](#NotificationMessage)
+
+*Additional Message Properties:*
+None
+
+*Implementations:*
+
+|  List of Implementations |
+|---|
+| [IDS-REST](../protocols/ids-rest/README.md#MessageProcessedNotificationMessage) |
+| [idscp2](../protocols/idscp2/ApplicationLayer/README.md) |
+| [multipart](../protocols/multipart#2-structure-of-a-multipart-message) |
+
+
+## Metadata Broker Interaction Messages
+
+See [Connector to Metadata Broker Communication](../sequence-diagrams/data-connector-to-metadata-broker/README.md)
+for information how to work with the Metadata Broker.
+
+
+## Message subtypes for other interaction
+Will be added in the future (TODO).

Communication/README.md

@@ -1,3 +1,30 @@
-# Communication
+# Overview
 
-The content in this folder will specify the communication between different IDS components.
+![sequence overview](./images/sequences_overview.png)
+
+| ID   | Sequence Specification | Protocols |
+|:-----|:---| :--- |
+| [1]  | [Connector to Connector](./sequence-diagrams/data-connector-to-data-connector#message-flows-for-connector-to-connector-communication) | [Multipart](./protocols/multipart); [IDS-REST protocol](./protocols/ids-rest); [IDSCP2 Transport Layer Protocol](./protocols/idscp2/TransportLayer); [IDSCP2 Application Layer protocol](./protocols/idscp2/ApplicationLayer) |
+| [2]  | Connector to Dynamic Attribute Provisioning Service (DAPS) |  |
+| [3]  | Connector to Participant Information Service (ParIS) |  |
+| [4]  | Connector to [Metadata Broker](./sequence-diagrams/data-connector-to-metadata-broker) | [Multipart](./protocols/multipart) |
+| [5]  | [Connector to Clearing House](./sequence-diagrams/data-connector-to-clearing-house) | [Multipart](./protocols/multipart) |
+| [6]  | Connector to App Store |  |
+| [7]  | Connector to Vocabulary Provider |  |
+| [8]  | ParIS to DAPS |  |
+| [9]  | Broker to DAPS |  |
+| [10] | Clearing House to DAPS |  |
+| [11] | App Store to DAPS |  |
+| [12] | Vocabulary Provider to DAPS |  |
+
+Since all IDS components are, at their core, a Connector, the connection of these to the DAPS (sequence 8-12) is designed in the same way as that of the Connector to the DAPS.
+
+## General Component Interaction
+
+In general, each communication between two components includes the following building blocks:
+
+![general_component_interaction_alt](./images/Interaction_Building_Blocks.png)
+
+Every communication requires an authenticated, integrity-protected and encrypted connection. The verification of the connector's identity is based on the IDS identity certificate (X.509v3), dynamic attributes and details for the company operating the connector. Additionally, connectors in the Trust or Trust+ Level need to prove their integrity with Remote Attestation based on a transmitted Attestation Report. Based on the secure channel, the desired IDS interaction is conducted as described in the Sequence Specifications above. If no secure channel can be established, the IDS interaction must not be executed.
+
+After the IDS Message was handled, the process/communication channel is terminated if no further interaction is required. Otherwise, the behavior depends on the utilized communication protocol. For a communication with the [IDS-REST protocol](./protocols/ids-rest) or [Multipart](./protocols/multipart), the communication channel will be re-established for every IDS Message. With the IDSCP2, the communication channel is established once via the [IDSCP2 Transport Layer Protocol](./protocols/idscp2/TransportLayer) and all IDS interactions will be executed via this channel with the [IDSCP2 Application Layer protocol](./protocols/idscp2/ApplicationLayer).