196 upate gitbook structure (#199)

* Create strucutre files for GitBook * Create .gitbook.yaml with root in documentation * Create SUMMARY.md for TOC * fixing links * Adapting Figure formatting to GitBook * Changing version numbers and updating changelog
International-Data-Spaces-Association · Oct 17, 2022 · 0eb9745 · 0eb9745
1 parent 08b0991
commit 0eb9745
Show file tree

Hide file tree

Showing 46 changed files with 254 additions and 204 deletions.
diff --git a/.gitbook.yaml b/.gitbook.yaml
@@ -0,0 +1,6 @@
+root: ./documentation/
+
+structure:
+    readme: README.md
+    summary: SUMMARY.md
+
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,11 +10,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Section 1.3  Relation to other IDSA assets
 - Minor editorial changes
+- Structural files for GitBook release
 
 ### Changed ###
 
 - Updating front matter with Maintainers and Contributors
 - Proving RAM 4.1 as GitBook
+- Formatting of figures changed to different style
 
 ### Removed ###
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Contributing to RAM 4.0
+# Contributing to RAM 4
 
 The IDS-RAM is one of the core deliverables of the  [IDSA](https://www.internationaldataspaces.org) that comes along with additional specifications in [IDS-G](https://github.com/International-Data-Spaces-Association/IDS-G).
 
@@ -25,6 +25,7 @@ the scope of your changes.
 **Bug Report**: As mentioned above, bug reports should be submitted as an issue. To give others
 the chance to reproduce the error in order to find a solution as quickly as possible, the report
 should at least include the following information:
+
 * Description: What did you expect and what happened instead?
 * Steps to reproduce (system specs included)
 * Relevant logs and/or media (optional): e.g. an image
@@ -36,6 +37,7 @@ The [labels](https://github.com/International-Data-Spaces-Association/IDS-RAM_4_
 There are two types of labels: one describes the content of the issue and should be used by the
 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`
 *  `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
@@ -78,4 +80,5 @@ An example of a very good commit might look like this: `feat![login]: add awesom
 Content that is added to the repository is published under the Creative Commons Attribution 4.0 license (see the [LICENSE.md file](./LICENSE.md)). That means that you implicitly accept that your content is treated by CC4.0 as soon as you push any changes to the main repository and can be further published, updated, or deleted. In particular, you grant the IDSA the copyright on your content and make sure that your addition does not conflict with any other copyright claim of your knowledge, for instance for used pictures or other graphics. 
 
 ## Versioning
+
 The next published version of the Reference Architecture Model will be Version 4.0.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
-# IDS RAM 4.0 #
+# IDS RAM 4 #
 
-Welcome to the IDS RAM 4.0 repository of the [IDSA](../../../idsa). 
+Welcome to the IDS RAM 4 repository of the [IDSA](../../../idsa). 
 
 ## Overview ##
 
@@ -44,12 +44,14 @@ The IDS-G contains specific details on specifications, e.g. APIs and their descr
   - [Section 4.2: Certification Perspective](./documentation/4_Perspectives_of_the_Reference_Architecture_Model/4_2_Certification_Perspective/README.md)
   - [Section 4.3: Governance Perspective](./documentation/4_Perspectives_of_the_Reference_Architecture_Model/4_3_Governance_Perspective/README.md)
 
-**Appendix**
+### Appendix ###
 
 - [Glossary](https://github.com/International-Data-Spaces-Association/IDS-G/tree/main/Glossary)
 
 ## Previous Versions ##
 
+- [IDS-RAM 4.1 - current -](https://github.com/International-Data-Spaces-Association/IDS-RAM_4_0/)
+- [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/)
 - [IDS RAM 1.0](https://internationaldataspaces.org/download/16652/)
diff --git a/documentation/1_Introduction/1_1_Goals_of_the_International_Data_Spaces.md b/documentation/1_Introduction/1_1_Goals_of_the_International_Data_Spaces.md
@@ -53,7 +53,7 @@ development of products and solutions for the market (see Figure below):
 ![ Three types of activities of the International Data
 Spaces](../media/image10.png)
 
-### Figure 1.1 : Three types of activities of the International Data Spaces
+##### Figure 1.1 : Three types of activities of the International Data Spaces
 
 The International Data Spaces aims at meeting the following strategic
 requirements:

diff --git a/documentation/1_Introduction/1_2_Purpose_and_Structure_of_the_document.md b/documentation/1_Introduction/1_2_Purpose_and_Structure_of_the_document.md
@@ -47,4 +47,4 @@ In addition, the Reference Architecture Model comprises three
 
 ![ General structure of Reference Architecture
 Model](../media/image11.png)
-#### Figure 1.2: General structure of the IDS Reference Architecture Model
+##### Figure 1.2: General structure of the IDS Reference Architecture Model
diff --git a/...Introduction/1_3_Relation_to_other_assets → ...roduction/1_3_Relation_to_other_assets.md b/...Introduction/1_3_Relation_to_other_assets → ...roduction/1_3_Relation_to_other_assets.md
@@ -2,8 +2,8 @@
 
 Based on this Reference Architecture Model a Certification Scheme is derived that validates the compliance of [participants](../3_Layers_of_the_Reference_Architecture_Model/3_1_Business_Layer/3_1_1_Roles_in_the_IDS.md) and [components](../3_Layers_of_the_Reference_Architecture_Model/3_5_System_Layer/3_5_0_System_Layer.md) to this Reference Architecture Model. Such components can be provided as Free and Open Source Software or proprietary software. The operation of a data space instance is described in the [IDSA Rulebook](../4_Perspectives_of_the_Reference_Architecture_Model/4_3_Governance_Perspective/4_3_10_IDS_RuleBook.md) based on the BLOFT (**B**usiness, **L**egal, **O**perational, **F**unctional, **T**echnical) aspects of a data space.
 
-The [Role of IDSA](../3_Layers_of_the_Reference_Architecture_Model/3_1_Business_Layer/3_1_1_Roles_in_the_IDS.md#category-4-governance-body) as an association and governance body is to keep those artifacts consitent while contiuously updating them based on the technological developments and user requirements. This is the IDSA magic triangle as depicted in figure [1.3.1].
+The [Role of IDSA](../3_Layers_of_the_Reference_Architecture_Model/3_1_Business_Layer/3_1_1_Roles_in_the_IDS.md#category-4-governance-body) as an association and governance body is to keep those artifacts consitent while contiuously updating them based on the technological developments and user requirements. This is the IDSA magic triangle as depicted in figure [1.3.1](#figure-131-idsa-magic-triangle).
 
 ![IDSA Magic Triangle](./media/IDSA_Magic_Triangle.png)
 
-### Figure 1.3.1: IDSA Magic Triangle
+##### Figure 1.3.1: IDSA Magic Triangle
diff --git a/documentation/1_Introduction/README.md b/documentation/1_Introduction/README.md
@@ -8,6 +8,8 @@
 
 [1.2 Purpose and Structure of the Reference Architecture](.\1_2_Purpose_and_Structure_of_the_document.md#purpose-and-structure-of-the-reference-architecture)
 
+[1.3 Relation to other IDSA assets](./1_3_Relation_to_other_assets.md#relation-to-other-idsa-assets)
+
 ## Files ##
 
 - [1_1_Goals_of_the_International_Data_Spaces.md](.\1_1_Goals_of_the_International_Data_Spaces.md)

diff --git a/...ata_Spaces/2_11_Contribution_of_the_IDS_to_Industry_4_0_and_the_Data_Economy.md b/...ata_Spaces/2_11_Contribution_of_the_IDS_to_Industry_4_0_and_the_Data_Economy.md
@@ -17,7 +17,7 @@ same time making sure data sovereignty is guaranteed for data owners.
 
 ![ Typical enterprise architecture
 stack](../media/image16.png)
-### Figure 2.11.1: Typical enterprise architecture stack
+##### Figure 2.11.1: Typical enterprise architecture stack
 
 In broadening the perspective from an individual use case scenario to a
 platform landscape view, the International Data Spaces positions itself
@@ -32,7 +32,7 @@ be connected to the International Data Spaces.
 
 ![ International Data Spaces connecting different cloud
 platforms](../media/image17.png)
-### Figure 2.11.2: International Data Spaces connecting different cloud platforms
+##### Figure 2.11.2: International Data Spaces connecting different cloud platforms
 
 With this integrating ambition, the International Data Spaces initiative
 positions itself in the context of cognate initiatives on both national

diff --git a/...Context_of_the_International_Data_Spaces/2_1_Data-Driven-Business_Ecosystems.md b/...Context_of_the_International_Data_Spaces/2_1_Data-Driven-Business_Ecosystems.md
@@ -27,4 +27,4 @@ resource (as shown by a number of examples in the Figure below).
 
 ![Data Sharing in
 Ecosystems](../media/image12.png)
-### Figure 2.1: Data Sharing in Ecosystems
+##### Figure 2.1: Data Sharing in Ecosystems
diff --git a/...xt_of_the_International_Data_Spaces/2_2_Data_Sovereignty_as_a_key_capability.md b/...xt_of_the_International_Data_Spaces/2_2_Data_Sovereignty_as_a_key_capability.md
@@ -26,7 +26,7 @@ itself, as not all data requires the same level of protection, and as
 the value contribution of data varies, depending on what class or
 category it can be subsumed under.
 
-## Definition of Data Sovereignty ##
+### Definition of Data Sovereignty ###
 
 ``Data Sovereignty is the ability of a natural or legal person to exclusively and sovereignly decide concerning the usage of data as an economic asset.``
 
diff --git a/..._Context_of_the_International_Data_Spaces/2_4_Data_Exchange_and_Data_Sharing.md b/..._Context_of_the_International_Data_Spaces/2_4_Data_Exchange_and_Data_Sharing.md
@@ -9,7 +9,7 @@ standards.
 
 ![Evolution of technical standards for data
 exchange](../media/image13.png)
-### Figure 2.4.1: Evolution of technical standards for data exchange
+##### Figure 2.4.1: Evolution of technical standards for data exchange
 
 The Figure above shows the evolution of
 technical standards for data exchange since the 1980s, using the example
@@ -41,4 +41,4 @@ also the Figure below:
 
 ![Data exchange vs. data
 sharing](../media/image14.png)
-### Figure 2.4.2 : Data Exchange and Data Sharing
+##### Figure 2.4.2 : Data Exchange and Data Sharing
diff --git a/documentation/2_Context_of_the_International_Data_Spaces/2_8_Blockchain.md b/documentation/2_Context_of_the_International_Data_Spaces/2_8_Blockchain.md
@@ -59,4 +59,4 @@ extraction (see Figure below).
 
 ![ General architectural patterns for data exchange and data
 sharing](../media/image15.png)
-### Figure 2.8 : General architectural patterns for data exchange and data sharing
+##### Figure 2.8 : General architectural patterns for data exchange and data sharing
diff --git a/...rs_of_the_Reference_Architecture_Model/3_1_Business_Layer/3-1-Business-layer.md b/...rs_of_the_Reference_Architecture_Model/3_1_Business_Layer/3-1-Business-layer.md
@@ -13,4 +13,4 @@ in the International Data Spaces, it can be considered a blueprint for
 the other, more technical layers. The Business Layer can therefore be
 used to verify the technical architecture of the International Data
 Spaces. In this sense, the Business Layer specifies the requirements to
-be addressed by the [Functional Layer](../../3_2_Functional_Layer/3_2_FunctionalLayer.md).
+be addressed by the [Functional Layer](../3_2_Functional_Layer/3_2_FunctionalLayer.md).
diff --git a/...f_the_Reference_Architecture_Model/3_1_Business_Layer/3_1_1_Roles_in_the_IDS.md b/...f_the_Reference_Architecture_Model/3_1_Business_Layer/3_1_1_Roles_in_the_IDS.md
@@ -69,15 +69,15 @@ be relevant in other contexts than the IDS RAM or may become relevant in
 the future, some potential basic roles are declared as (currently) "out
 of IDS RAM scope". The table below shows the basic roles defined in the IDS.
 
-|                 |       **Create**      |       **Own**      | **Certify / Verify** |       **Publish**       |       **Provide**      |      **Consume      |         **Use**         |      **Delete**     |   |   |   |   |   |
-|-----------------|:---------------------:|:------------------:|:--------------------:|:-----------------------:|:----------------------:|:-------------------:|:-----------------------:|:-------------------:|:-:|:-:|:-:|:-:|:-:|
-| **Connector**   |   Connector Creator   |   Connector Owner  |  Connector Certifier |   Connector Publisher   |   Connector Provider   |  (Out of RAM scope) |      Connector User     |  (Out of RAM scope) |   |   |   |   |   |
-| **Data**        |      Data Creator     |     Data Owner     |  (Out of RAM scope)  | Connector / Data Broker |      Data Provider     |    Data Consumer    |        Data User        |     Data Eraser     |   |   |   |   |   |
-| **Vocabulary**  |   Vocabulary Creator  |  Vocabulary Owner  |  (Out of RAM scope)  |   Vocabulary Publisher  |   Vocabulary Provider  | Vocabulary Consumer |     Vocabulary User     |  (Out of RAM scope) |   |   |   |   |   |
-| **Identity**    |    Identity Creator   |   Identity Owner   | Identity Verificator |   Identitiy Publisher   | Identity Authenticator |  (Out of RAM scope) |      Identity User      | Identity Eliminator |   |   |   |   |   |
-| **App**         |      App Creator      |      App Owner     |     App Certifier    |        App Broker       |      App Provider      |     App Consumer    |         App User        |   App Deleter (?)   |   |   |   |   |   |
-| **Transaction** | Transaction Initiator | (Out of RAM scope) |  Transaction Clearer |    (Out of RAM scope)   |   (Out of RAM scope)   |  (Out of RAM scope) | Transaction Participant |  (Out of RAM scope) |   |   |   |   |   |
-| **Service**     |    Service Creator    |    Service Owner   |   Service Certifier  |      Service Broker     |    Service Provider    |   Service Consumer  |       Service User      |  (Out of RAM scope) |   |   |   |   |   |
+|                 |       **Create**      |       **Own**      | **Certify / Verify** |       **Publish**       |       **Provide**      |      **Consume      |         **Use**         |      **Delete**     |  
+|-----------------|:---------------------:|:------------------:|:--------------------:|:-----------------------:|:----------------------:|:-------------------:|:-----------------------:|:-------------------:|
+| **Connector**   |   Connector Creator   |   Connector Owner  |  Connector Certifier |   Connector Publisher   |   Connector Provider   |  (Out of RAM scope) |      Connector User     |  (Out of RAM scope) |
+| **Data**        |      Data Creator     |     Data Owner     |  (Out of RAM scope)  | Connector / Data Broker |      Data Provider     |    Data Consumer    |        Data User        |     Data Eraser     |
+| **Vocabulary**  |   Vocabulary Creator  |  Vocabulary Owner  |  (Out of RAM scope)  |   Vocabulary Publisher  |   Vocabulary Provider  | Vocabulary Consumer |     Vocabulary User     |  (Out of RAM scope) |
+| **Identity**    |    Identity Creator   |   Identity Owner   | Identity Verificator |   Identitiy Publisher   | Identity Authenticator |  (Out of RAM scope) |      Identity User      | Identity Eliminator |
+| **App**         |      App Creator      |      App Owner     |     App Certifier    |        App Broker       |      App Provider      |     App Consumer    |         App User        |   App Deleter (?)   |
+| **Transaction** | Transaction Initiator | (Out of RAM scope) |  Transaction Clearer |    (Out of RAM scope)   |   (Out of RAM scope)   |  (Out of RAM scope) | Transaction Participant |  (Out of RAM scope) |
+| **Service**     |    Service Creator    |    Service Owner   |   Service Certifier  |      Service Broker     |    Service Provider    |   Service Consumer  |       Service User      |  (Out of RAM scope) |
 
 These basic roles are suitable to define technical tasks in the IDS and
 roles of the participants in detail. As this quite large number is,
@@ -107,13 +107,10 @@ symbols:
 
 There are four categories of roles:
 
-» Category 1: Core Participant
-
-» Category 2: Intermediary
-
-» Category 3: Software Developer
-
-» Category 4: Governance Body
+* Category 1: Core Participant
+* Category 2: Intermediary
+* Category 3: Software Developer
+* Category 4: Governance Body
 
 #### CATEGORY 1: CORE PARTICIPANT ####
 
@@ -146,10 +143,10 @@ as a legal entity or natural person executing control over data. This
 enables the Data Owner to define Data Usage Policies and provide access
 to its data. Data Ownership includes at least two major concepts:
 
-» having the (technical) means and the responsibility to define Usage
+* having the (technical) means and the responsibility to define Usage
 Contracts and Usage Policies, and to provide access to data; and
 
-» having the (technical) means and the responsibility to define the
+* having the (technical) means and the responsibility to define the
 Payment Model, including the model for reuse of data by third parties.
 
 The **Data Provider** makes data technically available in the IDS for
@@ -277,7 +274,7 @@ Creators to send their metadata. The metadata should be stored in an
 internal repository for being queried by Data Consumers in a structured
 manner. While the core of the metadata model must be specified by the
 International Data Spaces (i.e. by the Information Model, see
-  [Information Layer](../3_3_Information_Layer/README.md)), a Metadata Broker may extend the metadata model to manage additional
+[Information Layer](../3_3_Information_Layer/3_3_InformationLayer.md)), a Metadata Broker may extend the metadata model to manage additional
 metadata elements.
 
 After the Data Broker has provided the Data Consumer with the metadata
@@ -437,7 +434,7 @@ Spaces), a Dynamic Attribute Provisioning Service (DAPS, managing the
 dynamic attributes of the participants), and a service named Dynamic
 Trust Monitoring (DTM, for continuous monitoring of the security and
 behavior of the network. More details about identity management can be
-found in the [security perspective](../../4_Perspectives_of_the_Reference_Architecture_Model/4_1_Security_Perspective/README.md).
+found in the [security perspective](../../4_Perspectives_of_the_Reference_Architecture_Model/4_1_Security_Perspective/4_1_Security_Perspective.md).
 
 Typically, identities are created by the Identity Authority, then acting
 as an **Identity Creator**. In the sense of a directory, the authority
@@ -465,7 +462,7 @@ the App Developer typically covers the basic roles **App Creator** and,
 as long as the data app is not created on behalf, **App Owner**.
 
 To be deployable, a data app has to be compliant with the system
-architecture of the International Data Spaces (see [system layer](../3_5_System_Layer/README.md)). In
+architecture of the International Data Spaces (see [system layer](../3_5_System_Layer/3_5_0_System_Layer.md)). In
 addition, data Apps can be certified by a Certification Body in order to
 increase trust in these applications (especially with regard to Data
 Apps processing sensitive information).
@@ -479,7 +476,7 @@ model) with regard to its semantics, functionality, interfaces, etc.
 
 A Connector Developer provides software for implementing the
 functionality required by the International Data Spaces (i.e., through
-software components, as described in the [system layer](../3_5_System_Layer/README.md)). Unlike Data Apps,
+software components, as described in the [system layer](../3_5_System_Layer/3_5_0_System_Layer.md)). Unlike Data Apps,
 software is not provided by the App Store, but delivered over the
 Connector Developer's usual distribution channels, and used on the basis
 of individual agreements between the Connector Developer and the user
@@ -519,7 +516,7 @@ supervises the actions and decisions of the Evaluation Facilities.
 Thus, from the technical perspective, the basic roles **Connector
 Certifier**, **App Certifier** and **Service Certifier**.
 
-The Certification Scheme applied in the process is described in the [Certification Perspective](../../4_Perspectives_of_the_Reference_Architecture_Model/4_2_Certification_Perspective/README.md).
+The Certification Scheme applied in the process is described in the [Certification Perspective](../../4_Perspectives_of_the_Reference_Architecture_Model/4_2_Certification_Perspective/4_2_Certification_Perspective.md).
 
 ##### Standardization Organization #####