241 combine editrial and minor changes into a single merge for 42 (#242)

* Added paragraph to explain what's included in a Self-Description (#216)

* Added paragraph to explain what's included in a
Self-Description:
- Self-Description of the component
- Self-Description of the offered endpoints
- Self-Description of the offered data

* incorporated review by sebbader-sap

* Forgot one review comment

* Update 3_5_4_Metadata_Broker.md

Fixing typo and remving HTML tags

---------

Co-authored-by: Sebastian Steinbuss <[email protected]>

* chore: update functional view of connector (#217)

* chore: update functional view of connector

* chore: apply feedback

* Update figure 18 (#237)

* fixing wrong labels to broker

* Fixing missing text in Figure 1.3.1 (#239)

* adding missing label to figure 1.3.1
* adding picture source

* Update Changelog

Summarizing changes

* Update README.md

Updating version string

* Update README.md

fixing release history

---------

Co-authored-by: tom-rm-meyer-ISST <[email protected]>
Co-authored-by: Julia Pampus <[email protected]>

CHANGELOG.md

@@ -5,6 +5,30 @@ 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).
 
+## 4.2.0 ##
+
+### Added ###
+
+- Adding a detailled description for Self Descriptions at the IDS Metadata Broker
+
+### Changed ###
+
+- Updating figure 3.5.2.2 according to the text to improve readability and put it in line with the Dataspace Protocol
+
+
+### Removed ###
+
+- none
+
+### Deprecated ###
+
+- none
+
+### Fixed ###
+
+- Adding missing label in figure 1.3.1
+- 
+
 ## 4.1.2 ##
 
 ### Added ###
@@ -26,7 +50,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed ###
 
-- Misspelling of Metadata Broker in the RAM. Is now harmonized. 
+- Misspelling of Metadata Broker in the RAM. Is now harmonized.
 
 ## 4.1.1 ##
 

README.md

@@ -1,6 +1,6 @@
 # IDS RAM 4 #
 
-Welcome to the IDS RAM 4 repository of the [IDSA](../../../idsa). 
+Welcome to the IDS RAM 4 repository of the [IDSA](../../../idsa).
 
 ## Overview ##
 
@@ -11,15 +11,15 @@ Please consider the following information:
 - [License](./LICENSE.md),
 - [Changelog](./CHANGELOG.md),
 
-and check the open [issues](https://github.com/International-Data-Spaces-Association/IDS-RAM_4_0/issues) 
+and check the open [issues](https://github.com/International-Data-Spaces-Association/IDS-RAM_4_0/issues)
 and [pull requests](https://github.com/International-Data-Spaces-Association/IDS-RAM_4_0/pulls).
 
-The [IDS-G](https://github.com/International-Data-Spaces-Association/IDS-G) provides additional 
+The [IDS-G](https://github.com/International-Data-Spaces-Association/IDS-G) provides additional
 information to the IDS RAM.
 
 ## Scope ##
 
-The IDS RAM is complemented with additional documents and repositories. Most relevant in this 
+The IDS RAM is complemented with additional documents and repositories. Most relevant in this
 context is the [IDS-G](https://github.com/International-Data-Spaces-Association/IDS-G).
 
 In general, the IDS RAM contains the conceptual level including technology-agnostic specifications.
@@ -50,7 +50,8 @@ The IDS-G contains specific details on specifications, e.g. APIs and their descr
 
 ## Previous Versions ##
 
-- [IDS-RAM 4.1 - current -](https://github.com/International-Data-Spaces-Association/IDS-RAM_4_0/)
+- [IDS-RAM 4.2 - current -](https://github.com/International-Data-Spaces-Association/IDS-RAM_4_0/)
+- [IDS-RAM 4.1](https://github.com/International-Data-Spaces-Association/IDS-RAM_4_0/releases/tag/v.4.1.2)
 - [IDS-RAM 4.0](https://github.com/International-Data-Spaces-Association/IDS-RAM_4_0/releases/tag/v.4.0.0)
 - [IDS RAM 3.0](https://internationaldataspaces.org/download/16630/)
 - [IDS RAM 2.0](https://internationaldataspaces.org/download/16641/)

documentation/3_Layers_of_the_Reference_Architecture_Model/3_5_System_Layer/3_5_4_Metadata_Broker.md

@@ -1,12 +1,18 @@
 ### Metadata Broker ###
 
-The IDS Metadata Broker consists of an IDS Connector (see Section [3.5.2](./3_5_2_IDS_Connector.md#ids-connector)), an endpoint for the registration, publication, maintenance, and query of Self-Descriptions. Therefore, for any interaction with the IDS Metadata Broker, the processes defined on the Process Layer, the descriptions defined on the Information Layer, and descriptions defined on the System Layer can be applied. The Information Layer describes the message types for registration and query. An IDS Metadata Broker may provide additional services that in term must be described by using terms from the IDS Information Model in the respective Metadata Broker's Self-Description document.
+The IDS Metadata Broker is an IDS Connector (see Section [3.5.2](./3_5_2_IDS_Connector.md#ids-connector)), which contains an endpoint for the registration, publication, maintenance, and query of Self-Descriptions. 
+
+A Self-Description encapsulates information about IDS Connector itself and its capabilities and characteristics. This Self-Description contains information about the offered interfaces, the owner of the component and the metadata of the data offered by the component. A Self-Description is provided by the operator of the Connector. The Self-Description in total can be seen as metadata.
+
+An IDS Connector providing a service or data can send its Self-Description to a IDS Metadata Broker so that every participant is able to find it within the dataspace. The IDS Metadata Broker can be understood as a phone book. Within a dataspace, there can be multiple IDS Metadata Brokers allowing to distribute the IDS Metadata Broker functionality. It is up to the dataspace authority to decide if there is a leading IDS Metadata Broker or if the different instances operate independently.
+
+A participant can interact with an IDS Metadata Broker by using the processes defined on the Process Layer, the descriptions defined on the Information Layer, and descriptions defined on the System Layer. The Information Layer describes the message types for registration and query as well as their content. An IDS Metadata Broker may provide additional services that in term must be described by using terms from the IDS Information Model in the respective Metadata Broker's Self-Description document.
 
 **Note:  Even though the name might indicate a different purpose, an IDS Metadata Broker is *not* a message broker or provides any similar functions to distribute data assets actively by itself.**
 
 As a direct consequence of the IDS Connector-nature of the Metadata Broker, each instance must be compliant to the Connector Certification criteria and in particular provide the functionalities and endpoints of general Connectors. For instance, a Metadata Broker must provide a Self-Description that provides further information about itself for other IDS components. A Metadata Broker must also have a valid IDS Identity and use a valid DAT in its communication.
 
-In addition to these requirements for each IDS Connector, the Metadata Broker provides further functionalities for a data space. Its main purpose is the persistence and storing of Self-Description documents and offering efficient access and search functions on their content. It therefore requires a reliable and scalable internal database. As the Self-Description documents are encoded in RDF, usually JSON-LD, a graph-oriented database like a triple store or a property graph database might be used. Nevertheless also traditional SQL or NoSQL databases may be applied, which may not have the same native query support but still can be sufficient. In any case, the internal architecture of a Metadata Broker must be flexible enough to cope with extensions of the data scheme. The IDS Information Model can always be enriched with further attributes, so a Metadata Broker must also allow the persistence and querying of information which was not yet known at its deployment time. Furthermore, Metadata Brokers operated for certain domains or dedicated data spaces might also enforce the existence of attributes that are not covered by the core IDS Information Model or part of the IDS namespace. That implies that a certain Metadata Broker instances require Self-Descriptions which information content goes beyond the IDS Information Model. In such cases, the additional requirements are outlined in the Metadata Broker Self-Description as well as in the content of the return messages, in case a Connector has not set such attributes yet.
+In addition to these requirements for each IDS Connector, the Metadata Broker provides further functionalities for a data space. Its main purpose is the persistence and storing of Self-Description documents and offering efficient access and search functions on their content. It therefore requires a reliable and scalable internal database. As the Self-Description documents are encoded in RDF, usually JSON-LD, a graph-oriented database like a triple store or a property graph database might be used. Nevertheless also traditional SQL or NoSQL databases may be applied, which may not have the same native query support but still can be sufficient. In any case, the internal architecture of a Metadata Broker must be flexible enough to cope with extensions of the data scheme. The IDS Information Model can always be enriched with further attributes, so a Metadata Broker must also allow the persistence and querying of information which was not yet known at its deployment time. Furthermore, Metadata Brokers operated for certain domains or dedicated data spaces might also enforce the existence of attributes that are not covered by the core IDS Information Model or part of the IDS namespace. That implies that a certain Metadata Broker instance requires Self-Descriptions containing information content that uses extensions of the IDS Information Model. In such cases, the additional requirements are outlined in the Metadata Broker Self-Description as well as in the content of the return messages, in case a Connector has not set such attributes yet.
 
 Furthermore, a Metadata Broker implementation might add indexing or caching modules to reduce the query evaluation time. It can be generally expected that the amount of READ requests is significantly higher than the overall number of remote WRITE activities so a READ-optimized architecture can lead to better user experiences. Such design decisions however are in the responsibility of the operator.
 

documentation/README.md

@@ -1,4 +1,4 @@
-# IDS-RAM 4.1.2 #
+# IDS-RAM 4.2.0 #
 
 ## Table of Content ##