Merge pull request #701 from dg-tsy/main

Data Governance KIT Documentation

docs-kits/kits/Data Governance Kit/Software Development View/page_software-development-view.md

@@ -0,0 +1,64 @@
+---
+id: Data Governance Kit Development View
+title: Development View
+description: 'Data Governance Kit'
+sidebar_position: 1
+---
+## Data Governance KIT
+
+<!--
+ * Copyright (c) 2021,2023 T-Systems International GmbH
+ * Copyright (c) 2021,2023 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This documentation and the accompanying materials are made available under the
+ * terms of the Creative Commons Attribution 4.0 International License,  which is available at
+ * https://creativecommons.org/licenses/by/4.0/legalcode.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ * SPDX-License-Identifier: CC-BY-4.0
+![DatGov Kit Banner](/resources/DatGovKit-Icon.png)
+-->
+
+This document describes the foundations of the Data Governance KIT (=Keep It Together).
+
+For more information see
+
+* [Adoption View](../page_adoption-view.md)
+* [Operation View](../page_software-operation-view.md)
+
+### Overview
+
+The Data Governance Kit provides a set of API specifications which would help the application developers in developing the abstraction layer of EDC to simplify the data governance. This should be helpful in building products but won't be one in itself. The client API from Data Governance Kit should cover the most typical Data Provider and Consumer functions, including publishing and managing data offers, managing policies, listing data transfers and contract negotiations. Important to note here is that the API specifications makes it possible to interact with multiple EDC connectors at once.
+
+### High Level Architecture
+
+As it would be clear now that the Data Governance Kit acts as an abstraction layer for multiple EDC Connctors and hides the EDC complexities behind it. This is achieved by using the below concepts:
+
+* Staging (or Management )
+* Publication
+
+The staging or Management refers to the creation, updation, deletion of various Assets, Policies and Contract Offers locally within the Governance KIT before actually sending those to the connectors. The users can create as many Assets, Policies or Contract Offers, get those reviewed and approved by any manual or automatic workflow process. Once the users are sure that now the data is ready to be sent to Connectors, the Publication process kicks in. Using the publication process, all the reviewed/approved assets, policies and contract offers can be sent to the required connectors. The following high level architecture provides more details.
+
+![Data Governance Kit High Level Architecture](../resources/Data%20Governance%20KIT_%20Big%20Picture.png)
+
+### API Specifications
+
+The Data Governance KIT API specifications can be found here.
+
+[Data Governance Kit Swagger API Specifications](https://app.swaggerhub.com/apis-docs/TSI-Germany/data-governance_kit/0.0.1-SNAPSHOT)
+
+## NOTICE
+
+This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
+
+* SPDX-License-Identifier: CC-BY-4.0
+* SPDX-FileCopyrightText: 2023,2024 T-Systems International GmbH
+* SPDX-FileCopyrightText: 2022,2023 Contributors to the Eclipse Foundation

docs-kits/kits/Data Governance Kit/page_adoption-view.md

@@ -0,0 +1,92 @@
+---
+id: Data Governance Kit Adoption View
+title: Adoption View
+description: 'Data Governance Kit'
+sidebar_position: 2
+---
+## Data Governance KIT
+
+<!--
+ * Copyright (c) 2024 T-Systems International GmbH
+ * Copyright (c) 2021,2023 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This documentation and the accompanying materials are made available under the
+ * terms of the Creative Commons Attribution 4.0 International License,  which is available at
+ * https://creativecommons.org/licenses/by/4.0/legalcode.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ * SPDX-License-Identifier: CC-BY-4.0
+![DatGov Kit Banner](/img/DatGovKit/DatGovKit-Icon.png)
+-->
+
+This document describes the foundations of the Data Governance KIT (=Keep It Together).
+
+For more information see
+
+* [Development View and Architecture](./Software%20Development%20View/page_software-development-view.md)
+* [Operation View](./page_software-operation-view.md)
+
+### Vision & Mission
+
+#### Vision
+
+Data Governance KIT (DGK) has the objective to enable and simplify data governance within Catena-X by providing API specifications for the KIT so as to enable the application developers to create applications around these API specifications. The decentral components of the DGK enable dataspace participants to exercise control over all data governance related topics, e.g.
+
+* Manage data assets, policies and contracts in a convenient way, i.e. via templates/blueprints
+* Streamline the process of publishing data into the dataspace
+* Providing transparency of all data offers for a given organization
+* Monitor data exchange
+* Multi EDC Management
+
+The decentral components of the DGK are tightly coupled with the dataspace connector (EDC) and backend data services. Together with the connector and backend data services a streamlined and trusted environment for dataspace participation can be built.
+
+#### Mission
+
+The mission is to provide all the required details about Adoption View, Operation View and Development View for the KIT as well as to drive the standardization topics for EDC Management APIs.
+
+### Overview
+
+The Data Governance Kit will provide the API specifications which in turn will enable the develpment of the decentralized components that links Backend Data Services with Data Space Connectors to ease the management of the data governance aspects. This should be helpful in building products but won't be one in itself. The client API from Data Governance Kit should cover the most typical Data Provider and Consumer functions, including publishing and managing data offers, managing policies, listing data transfers and contract negotiations.
+
+![Data Governance Kit Overview](./resources/DGK%20Overview.png)
+
+### Business Value
+
+Data sovereignty is one of the core value propositions of Catena-X. EDC contributes some core functions but it does not provide a holistic view of all data governance topics within a data provider/consumer space. Therefore, the KIT provides answers to the following questions:
+
+* How to shield the complexity of publishing data into dataspace via EDC from Backend Data Services?
+* How to ensure that Backend Data Services publish data with correct policies and under the correct contract offers?
+* How to manage multiple EDCs?
+* How to document transfers and negotiated policies in a single place?
+* How to see which policy is active and when does it expire?
+
+#### Data Provider
+
+Any party who provides data (for example by a backend database or other supported Applications or Services), for example an Automotive OEM (original equipment manufacturer). Any party who wants to maintain multiple connectors and provide the data to other consumers via those connectors as well as use the governance features from Data Governance Kit.
+
+#### Data Consumer
+
+Any party who wants to consume the data made available by the data providers and use the governance features from Data Governance Kit.
+
+### Target Group / Service/ Apps that need the enabler
+
+* All Data Providers
+* All Data Consumers
+* Any Enablement Service Provider
+* Any Business Application Provider
+
+## NOTICE
+
+This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
+
+* SPDX-License-Identifier: CC-BY-4.0
+* SPDX-FileCopyrightText: 2023,2024 T-Systems International GmbH
+* SPDX-FileCopyrightText: 2022,2023 Contributors to the Eclipse Foundation

docs-kits/kits/Data Governance Kit/page_changelog.md

@@ -0,0 +1,50 @@
+---
+id: Data Governance Kit Changelog
+title: Changelog
+description: 'Data Governance Kit'
+sidebar_position: 1
+---
+<!--
+ * Copyright (c) 2021,2023 T-Systems International GmbH
+ * Copyright (c) 2021,2023 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This documentation and the accompanying materials are made available under the
+ * terms of the Creative Commons Attribution 4.0 International License,  which is available at
+ * https://creativecommons.org/licenses/by/4.0/legalcode.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ * SPDX-License-Identifier: CC-BY-4.0
+ ![DatGov Kit Banner](./resources/DatGovKit-Icon.png)
+-->
+
+### Data Governance KIT
+
+All notable changes to the Data Governance KIT (=Keep It Together) will be documented in this file.
+
+## [0.1.0] - 2024-03-08
+
+### Added
+
+- First Version for Adoption View
+- First Version for Development View
+- Notice
+
+### Changed
+
+### Removed
+
+## NOTICE
+
+This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
+
+- SPDX-License-Identifier: CC-BY-4.0
+- SPDX-FileCopyrightText: 2023,2024 T-Systems International GmbH
+- SPDX-FileCopyrightText: 2022,2023 Contributors to the Eclipse Foundation

docs-kits/kits/Data Governance Kit/resources/MDX Files/create-asset-1.api.mdx

@@ -0,0 +1,42 @@
+---
+id: create-asset-1
+title: "Creates a new asset revision"
+description: "Creates a new asset revision"
+sidebar_label: "Creates a new asset revision"
+hide_title: true
+hide_table_of_contents: true
+api: {"tags":["DGK Asset"],"operationId":"createAsset_1","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"properties":{"type":"object","additionalProperties":{"type":"object"}},"privateProperties":{"type":"object","additionalProperties":{"type":"object"}},"dataAddress":{"type":"object","properties":{"properties":{"type":"object","additionalProperties":{"type":"object"}}}}}}}},"required":true},"responses":{"200":{"description":"Asset was created successfully. Returns the asset Id","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"level":{"type":"string"},"result":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string"}}}}}}}}}}},"400":{"description":"Request body was malformed","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"level":{"type":"string"},"result":{"type":"string"}}}}}},"409":{"description":"Asset could not be created, because it does already exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"level":{"type":"string"},"result":{"type":"string"}}}}}}},"description":"Creates a new asset revision","method":"post","path":"/assets","servers":[{"url":"https://dgk.cx.dev.dih-cloud.com","description":"Generated server url"}],"jsonRequestBodyExample":{"id":"string","properties":{},"privateProperties":{},"dataAddress":{"properties":{}}},"info":{"title":"data-governance-kit","description":"REST API Contract for Data Governance KIT","version":"0.0.1-SNAPSHOT"},"postman":{"name":"Creates a new asset revision","description":{"type":"text/plain"},"url":{"path":["assets"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}}
+sidebar_class_name: "post api-method"
+info_path: docs-kits/kits/Data Governance Kit/resources/data-governance-kit
+custom_edit_url: null
+---
+
+import ApiTabs from "@theme/ApiTabs";
+import MimeTabs from "@theme/MimeTabs";
+import ParamsItem from "@theme/ParamsItem";
+import ResponseSamples from "@theme/ResponseSamples";
+import SchemaItem from "@theme/SchemaItem";
+import SchemaTabs from "@theme/SchemaTabs";
+import DiscriminatorTabs from "@theme/DiscriminatorTabs";
+import TabItem from "@theme/TabItem";
+
+## Creates a new asset revision
+
+
+
+Creates a new asset revision
+
+<MimeTabs><TabItem label={"application/json"} value={"application/json-schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Request Body</strong><strong style={{"fontSize":"var(--ifm-code-font-size)","color":"var(--openapi-required)"}}> required</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"id"} required={false} deprecated={undefined} schemaDescription={undefined} schemaName={"string"} qualifierMessage={undefined} defaultValue={undefined}></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>properties</strong><span style={{"opacity":"0.6"}}> object</span></summary><div style={{"marginLeft":"1rem"}}><li><div><code>property name*</code><span style={{"opacity":"0.6"}}> object</span></div></li></div></details></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>privateProperties</strong><span style={{"opacity":"0.6"}}> object</span></summary><div style={{"marginLeft":"1rem"}}><li><div><code>property name*</code><span style={{"opacity":"0.6"}}> object</span></div></li></div></details></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>dataAddress</strong><span style={{"opacity":"0.6"}}> object</span></summary><div style={{"marginLeft":"1rem"}}><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>properties</strong><span style={{"opacity":"0.6"}}> object</span></summary><div style={{"marginLeft":"1rem"}}><li><div><code>property name*</code><span style={{"opacity":"0.6"}}> object</span></div></li></div></details></SchemaItem></div></details></SchemaItem></ul></details></TabItem></MimeTabs><div><ApiTabs><TabItem label={"200"} value={"200"}><div>
+
+Asset was created successfully. Returns the asset Id
+
+</div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} deprecated={undefined} schemaDescription={undefined} schemaName={"string"} qualifierMessage={undefined} defaultValue={undefined}></SchemaItem><SchemaItem collapsible={false} name={"level"} required={false} deprecated={undefined} schemaDescription={undefined} schemaName={"string"} qualifierMessage={undefined} defaultValue={undefined}></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>result</strong><span style={{"opacity":"0.6"}}> object</span></summary><div style={{"marginLeft":"1rem"}}><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>items</strong><span style={{"opacity":"0.6"}}> object[]</span></summary><div style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"assetId"} required={false} deprecated={undefined} schemaDescription={undefined} schemaName={"string"} qualifierMessage={undefined} defaultValue={undefined}></SchemaItem></div></details></SchemaItem></div></details></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"string\",\n  \"level\": \"string\",\n  \"result\": {\n    \"items\": [\n      {\n        \"assetId\": \"string\"\n      }\n    ]\n  }\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem><TabItem label={"400"} value={"400"}><div>
+
+Request body was malformed
+
+</div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} deprecated={undefined} schemaDescription={undefined} schemaName={"string"} qualifierMessage={undefined} defaultValue={undefined}></SchemaItem><SchemaItem collapsible={false} name={"level"} required={false} deprecated={undefined} schemaDescription={undefined} schemaName={"string"} qualifierMessage={undefined} defaultValue={undefined}></SchemaItem><SchemaItem collapsible={false} name={"result"} required={false} deprecated={undefined} schemaDescription={undefined} schemaName={"string"} qualifierMessage={undefined} defaultValue={undefined}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"string\",\n  \"level\": \"string\",\n  \"result\": \"string\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem><TabItem label={"409"} value={"409"}><div>
+
+Asset could not be created, because it does already exist.
+
+</div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} deprecated={undefined} schemaDescription={undefined} schemaName={"string"} qualifierMessage={undefined} defaultValue={undefined}></SchemaItem><SchemaItem collapsible={false} name={"level"} required={false} deprecated={undefined} schemaDescription={undefined} schemaName={"string"} qualifierMessage={undefined} defaultValue={undefined}></SchemaItem><SchemaItem collapsible={false} name={"result"} required={false} deprecated={undefined} schemaDescription={undefined} schemaName={"string"} qualifierMessage={undefined} defaultValue={undefined}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"string\",\n  \"level\": \"string\",\n  \"result\": \"string\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>
+