From f3a5122f000a8fda140f59e6501139609b3af73c Mon Sep 17 00:00:00 2001 From: Sahil Aggarwal Date: Wed, 13 Nov 2024 16:00:49 +0100 Subject: [PATCH 1/5] updated documentation --- CHANGELOG.md | 5 ++ docs/architecture/1-introduction-and-goals.md | 14 ++++ .../2-architecture-constraints.md | 20 +++++ .../3-system-scope-and-context.md | 35 +++++++++ docs/architecture/4-runtime-view.md | 77 +++++++++++++++++++ docs/architecture/5-deployment-view.md | 24 ++++++ docs/architecture/6-concepts.md | 53 +++++++++++++ docs/architecture/7-quality-scenarios.md | 20 +++++ docs/{ => architecture}/documentation.md | 0 docs/architecture/glossary.md | 15 ++++ 10 files changed, 263 insertions(+) create mode 100644 docs/architecture/1-introduction-and-goals.md create mode 100644 docs/architecture/2-architecture-constraints.md create mode 100644 docs/architecture/3-system-scope-and-context.md create mode 100644 docs/architecture/4-runtime-view.md create mode 100644 docs/architecture/5-deployment-view.md create mode 100644 docs/architecture/6-concepts.md create mode 100644 docs/architecture/7-quality-scenarios.md rename docs/{ => architecture}/documentation.md (100%) create mode 100644 docs/architecture/glossary.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 354d48b..482798a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ 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). +## 0.5.2 +### Added +## fixed +- Updated the documentation structure according to Arc42 template + ## 0.5.1 ### Added ## fixed diff --git a/docs/architecture/1-introduction-and-goals.md b/docs/architecture/1-introduction-and-goals.md new file mode 100644 index 0000000..3b1c635 --- /dev/null +++ b/docs/architecture/1-introduction-and-goals.md @@ -0,0 +1,14 @@ +## 1 Introduction and goals + +The Semantic Hub is a logical and architectural component of Tractus-X. It stores Semantic Model definitions and allows the generation of several artifacts. +The source code under this folder contains reference implementations of the SLDT Semantic Hub + + +### NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-semantic-hub.git \ No newline at end of file diff --git a/docs/architecture/2-architecture-constraints.md b/docs/architecture/2-architecture-constraints.md new file mode 100644 index 0000000..616cadb --- /dev/null +++ b/docs/architecture/2-architecture-constraints.md @@ -0,0 +1,20 @@ +## 2 Architecture and constraints + +### Overall Architecture +The SLDT Semantic Hub stores Semantic Model definitions and allows the generation of several artifacts. It restricts access to the models by authentication via a token and authorization via roles in the token claims. Therefore, the Hub interacts with a Keycloak instance. The models are created in the Hub during our governance process as depicted below. +```mermaid +graph LR + SemanticHub[Semantic hub] -- "read models" --> Data[Data Consumer/Provider] + Keycloak --"PUB Key for token validation" --> SemanticHub + Github[Github Models Repository] -- "synchronize models from the governance process" --> SemanticHub +``` + + +### NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-semantic-hub.git \ No newline at end of file diff --git a/docs/architecture/3-system-scope-and-context.md b/docs/architecture/3-system-scope-and-context.md new file mode 100644 index 0000000..a34a100 --- /dev/null +++ b/docs/architecture/3-system-scope-and-context.md @@ -0,0 +1,35 @@ +## 3 System scope and context + +### Business Context + +```mermaid +%%{init: {"flowchart": {"curve": "linear"} }}%% +flowchart LR + DC(Data Consumer) + DP(Data Provider) + K(Keycloak) + + subgraph Semantic Hub + SHB(Semantic Hub Backend) + SH[(Sematic Hub postgres)] + end + + SHB <-->|Find submodels / metadata| DC + SHB <-->|Submodel creation \n provide metadata| DP + + SHB <--> SH + + K -->|Public key for token validation| SHB + + DC <-->|Token request| K + DP <-->|Token request| K +``` + +### NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-semantic-hub.git \ No newline at end of file diff --git a/docs/architecture/4-runtime-view.md b/docs/architecture/4-runtime-view.md new file mode 100644 index 0000000..7793cbd --- /dev/null +++ b/docs/architecture/4-runtime-view.md @@ -0,0 +1,77 @@ +## 4 Runtime-view + +### Upload of an aspect model +```mermaid +sequenceDiagram + actor ModelAdmin as Model Admin + participant SemanticHub as Semantic hub + participant TripleStore as TripleStore + + ModelAdmin ->>+ SemanticHub: Upload aspect model file (.ttl) + loop validation + SemanticHub ->>+ SemanticHub: Check if aspect model is complaint with bamm/samm (using sdk) + SemanticHub ->>+ TripleStore: Check if aspect model already exists + Note over SemanticHub, TripleStore: If the aspect model exists and is in release status,
the upload will be rejected.
If the aspect model exists in draft status,
upload will be accepted. + SemanticHub ->>+ TripleStore: Check if external referenceses exists + Note over SemanticHub, TripleStore: If an external reference does not exists,
the upload will be rejected.
Should we allow to reference namespaces,
in DRAFT state? + TripleStore -->> SemanticHub: response ok + end + note over ModelAdmin, SemanticHub: The model admin provides the release status
(RELEASED/DRAFT) upon upload + SemanticHub ->>+ SemanticHub: Add the release status as triple to the model + SemanticHub ->>+ TripleStore: Write all triples to TripleStore + TripleStore -->> SemanticHub: response ok + SemanticHub -->> ModelAdmin: Response upload successful +``` +| Validation | Description Value | +|---|---| +| BAMM compliance | Checks if the model is compliant with the BAMM. The BAMM SDK does provide the validation logic. | +| Model Status check (RELEASE vs DRAFT) | Uploads will always accepted when there are no existing namespace:version combination in the TripleStore. For a model in DRAFT state, uploads will always be accepted. For a model in RELEASE state, uploads will be denied. RELEASED models are immutable. | +| External reference check | It will be checked if all exernal references are available in the TripleStore. The BAMM SDK does provide a mechanisim where the resolving against the TripleStore can be integrated. | + + +## Download of the documentation of an Aspect Model +```mermaid +sequenceDiagram + actor ModelAdmin as Model Admin + participant SemanticHub as Semantic hub + participant TripleStore as TripleStore + + ModelAdmin ->>+ SemanticHub: Get documentation for aspect model com.catenax:0.0.1:Sample + SemanticHub ->>+ TripleStore: Resolve aspect model with all references based on provided urn com.catenax:0.0.1:Sample + TripleStore -->> SemanticHub: response + SemanticHub ->>+ SemanticHub: generate documentation based on the response from TripleStore + SemanticHub -->> ModelAdmin: respond with generated documenation +``` +``` + +Example queries to resolve an aspect model with all references: +Construct Query +``` +@prefix ns: + +CONSTRUCT { +?s ?p ?o . +} WHERE { +bind( ns: as ?aspect) +?aspect (<>|!<>)* ?s . // resolves all references +?s ?p ?o . +} +Search for Aspect Models +The current search API can stay as is. Below is an example query for selecting bamm properties: +Search Queries +CONSTRUCT { +?s ?p ?o . +} WHERE { +FILTER ( $param == ?o ) // Custom filter can be added here. +?s ?p ?o . +} +``` + +### NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-semantic-hub.git \ No newline at end of file diff --git a/docs/architecture/5-deployment-view.md b/docs/architecture/5-deployment-view.md new file mode 100644 index 0000000..a87d710 --- /dev/null +++ b/docs/architecture/5-deployment-view.md @@ -0,0 +1,24 @@ +## 5 Deployment-view + +For Deployment needed: + +- Webserver + +- Kubernetes-Cluster + +- Helm + +To deploy this system, you need to use the Helm Chart in a running +Kubernetes cluster. The Helm Chart is located under "charts/semantic-hub". +In case you don't have a running cluster, you can set up one by yourself +locally, using minikube. For further information checkout the [readme.md](https://github.com/eclipse-tractusx/sldt-semantic-hub/blob/main/README.md). + + +### NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-bpn-discovery.git \ No newline at end of file diff --git a/docs/architecture/6-concepts.md b/docs/architecture/6-concepts.md new file mode 100644 index 0000000..451e2c1 --- /dev/null +++ b/docs/architecture/6-concepts.md @@ -0,0 +1,53 @@ +## 6 Concept + +### Overall Concept + +#The overall concept can be found under **2 Architecture and +constraints**. + +### Semantic Hub + +Example Aspect Model +``` +@prefix xsd: . +@prefix bamm: . +@prefix : . + + +:DocumentationSimple a bamm:Aspect; +bamm:name "ManufacturerDocumentationSimple"; +bamm:preferredName "ManufacturerDocumentation"@en; +bamm:description "The Submodel defines a simplified set of manufacturer documentation to bring about information from manufacturer to operator of industrial equipment."@en; + +:documents a bamm:Property; +bamm:name "documents"; +bamm:preferredName "documents"@en; +bamm:description "Set of documents"@en; +``` + +The Semantic Hub will add the release status as triple upon upload: +Release Status +``` +@prefix aux: + + aux:releaseStatus aux:DRAFT . +``` + +## Package +| No | Rule | Example | +|----|-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 1. | A package is defined by the urn prefix until "#". | net.catenax.semantics.product:1.2.0# | +| 2. | A package can contain one or multiple aspects. | Example 1: net.catenax.semantics.traceability:1.2.0#Traceability Example 2: net.catenax.semantics.product:1.2.0#ProductDescription net.catenax.semantics.product:1.2.0#ProductUsage net.catenax.semantics.product:1.2.0#ProductDetails | +| 3. | Multiple versions of a package can exists. | Possible: net.catenax.semantics.product:1.2.0 net.catenax.semantics.product:4.2.0 | +| 4. | The versioning applies to the package. All aspects and model elements scoped to a package have the same version. | Possible: net.catenax.semantics.product:1.2.0#ProductDescription net.catenax.semantics.product:1.2.0#ProductUsage net.catenax.semantics.product:1.2.0#ProductDetails Possible:net.catenax.semantics.product:4.3.0#ProductDescription net.catenax.semantics.product:4.3.0#ProductUsage net.catenax.semantics.product:4.3.0#ProductDetails Not Possible: net.catenax.semantics.product:1.3.0#ProductDescription net.catenax.semantics.product:1.2.0#ProductUsage net.catenax.semantics.product:3.2.0#ProductDetails | +| 5. | All aspect models and model elements scoped to a package have the same status. | Possible: net.catenax.semantics.product:1.2.0#ProductDescription → RELEASE, net.catenax.semantics.product:1.2.0#ProductUsage → RELEASE net.catenax.semantics.product:1.2.0#ProductDetails → RELEASE Not Possible: net.catenax.semantics.product:1.2.0#ProductDescription → RELEASE, net.catenax.semantics.product:1.2.0#ProductUsage → DRAFT | + + +### NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-semantic-hub.git \ No newline at end of file diff --git a/docs/architecture/7-quality-scenarios.md b/docs/architecture/7-quality-scenarios.md new file mode 100644 index 0000000..83abc0f --- /dev/null +++ b/docs/architecture/7-quality-scenarios.md @@ -0,0 +1,20 @@ +## 7 Quality scenarios + +### Quality Requirements + +| Tool | Description | +|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Veracode | "Veracode enables you to quickly and cost-effectively scan software for flaws and get actionable source code analysis results." [Link](https://www.veracode.com) | +| Trivy | "Trivy is a simple and comprehensive vulnerability/misconfiguration/secret scanner for containers and other artifacts. Trivy detects vulnerabilities of OS packages and language-specific packages." [Link](https://aquasecurity.github.io/trivy/v0.34/) | +| SonarCloud | "SonarCloud's static analysis detects Bugs and Code Smells in your repositories and provides the feedback you need to write better code." [Link](https://www.sonarsource.com/products/sonarcloud/) | + + + +### NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-semantic-hub.git \ No newline at end of file diff --git a/docs/documentation.md b/docs/architecture/documentation.md similarity index 100% rename from docs/documentation.md rename to docs/architecture/documentation.md diff --git a/docs/architecture/glossary.md b/docs/architecture/glossary.md new file mode 100644 index 0000000..f9c0544 --- /dev/null +++ b/docs/architecture/glossary.md @@ -0,0 +1,15 @@ +## Glossary + +| Term | Description | +|----------|------------------------------------------------------------------------------------------------------------| +| Keycloak | Keycloack is an open-source Identity Management and Access management solution that allows Single Sign-On. | +| Realm | Manages a set of users, credentials, roles. Authenticates the users it controls. | +| SAMM | Semantic Aspect Meta Model | +### NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-semantic-hub.git \ No newline at end of file From 0bc098933286c0005a83ad81bea33955495832cb Mon Sep 17 00:00:00 2001 From: Sahil Aggarwal Date: Wed, 13 Nov 2024 16:09:22 +0100 Subject: [PATCH 2/5] updated documentation --- docs/architecture/4-runtime-view.md | 2 +- docs/architecture/5-deployment-view.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/4-runtime-view.md b/docs/architecture/4-runtime-view.md index 7793cbd..282b22b 100644 --- a/docs/architecture/4-runtime-view.md +++ b/docs/architecture/4-runtime-view.md @@ -65,7 +65,7 @@ CONSTRUCT { FILTER ( $param == ?o ) // Custom filter can be added here. ?s ?p ?o . } -``` + ### NOTICE diff --git a/docs/architecture/5-deployment-view.md b/docs/architecture/5-deployment-view.md index a87d710..f7eec26 100644 --- a/docs/architecture/5-deployment-view.md +++ b/docs/architecture/5-deployment-view.md @@ -21,4 +21,4 @@ This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LIC - SPDX-License-Identifier: Apache-2.0 - SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH - SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation -- Source URL: https://github.com/eclipse-tractusx/sldt-bpn-discovery.git \ No newline at end of file +- Source URL: https://github.com/eclipse-tractusx/sldt-semantic-hub.git \ No newline at end of file From 62500e6b24fd9f6929854d33995c6be102f51a2f Mon Sep 17 00:00:00 2001 From: Sahil Aggarwal Date: Wed, 13 Nov 2024 16:11:02 +0100 Subject: [PATCH 3/5] updated documentation --- docs/architecture/4-runtime-view.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/architecture/4-runtime-view.md b/docs/architecture/4-runtime-view.md index 282b22b..a82326f 100644 --- a/docs/architecture/4-runtime-view.md +++ b/docs/architecture/4-runtime-view.md @@ -46,6 +46,8 @@ sequenceDiagram Example queries to resolve an aspect model with all references: Construct Query +``` + ``` @prefix ns: @@ -65,7 +67,7 @@ CONSTRUCT { FILTER ( $param == ?o ) // Custom filter can be added here. ?s ?p ?o . } - +``` ### NOTICE From 5663d4068f56dcd91cdbae7c75e86f0c5da73a79 Mon Sep 17 00:00:00 2001 From: Sahil Aggarwal Date: Sun, 17 Nov 2024 17:46:25 +0100 Subject: [PATCH 4/5] updated documentation --- .../3-system-scope-and-context.md | 46 +++--- docs/architecture/4-runtime-view.md | 2 +- docs/architecture/5-deployment-view.md | 2 +- ...concepts.md => 6-crosscutting-concepts.md} | 61 ++++++- docs/architecture/documentation.md | 150 ------------------ docs/architecture/glossary.md | 2 +- 6 files changed, 89 insertions(+), 174 deletions(-) rename docs/architecture/{6-concepts.md => 6-crosscutting-concepts.md} (75%) delete mode 100644 docs/architecture/documentation.md diff --git a/docs/architecture/3-system-scope-and-context.md b/docs/architecture/3-system-scope-and-context.md index a34a100..6180cbd 100644 --- a/docs/architecture/3-system-scope-and-context.md +++ b/docs/architecture/3-system-scope-and-context.md @@ -3,28 +3,34 @@ ### Business Context ```mermaid -%%{init: {"flowchart": {"curve": "linear"} }}%% -flowchart LR - DC(Data Consumer) - DP(Data Provider) - K(Keycloak) - - subgraph Semantic Hub - SHB(Semantic Hub Backend) - SH[(Sematic Hub postgres)] - end - - SHB <-->|Find submodels / metadata| DC - SHB <-->|Submodel creation \n provide metadata| DP - - SHB <--> SH - - K -->|Public key for token validation| SHB - - DC <-->|Token request| K - DP <-->|Token request| K +graph LR + Keycloak -- "administrates the authorization token" <--> Semantic_Hub[Semantic Hub] + Semantic_Hub -- "view models with user interface" --> Portal[Portal] + Use_case[Github Models Repository] -- "Uploads the Aspect model" --> Semantic_Hub ``` +| Neighbor | Description | Example | +|--------------------------|---------------------------------------------------------------------|----------------------------------------------------------| +| Github Models Repository | Uploads aspect model on Semantic hub with some urn | A provider/use case uploads model with urn model-1.0. | +| Semantic Hub | Provides the endpoints to view, add, update or delete aspect models | | +| Keycloak | Keycloak is used for token validation | | +| Portal | User interface used to view aspect models | + +### Technical Context +```mermaid +graph LR + Keycloak -- "administrates the authorization token" <--> Semantic_Hub[Semantic Hub] + Semantic_Hub -- "view models via GET https: /models/{urn}" --> Portal[Portal] + Use_case[Github Models Repository] -- "Uploads the Aspect model via POST https: /models" --> Semantic_Hub +``` + +| Neighbor | Description | +|--------------------------|--------------------------------------------------------------------------| +| Github Models Repository | Uploads or modify models in Semantic Hub | +| Portal | Views the Aspect Models through user interface | +| Keycloak | Generates token for users and provides id management of user and service | + + ### NOTICE This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/docs/architecture/4-runtime-view.md b/docs/architecture/4-runtime-view.md index a82326f..37095bc 100644 --- a/docs/architecture/4-runtime-view.md +++ b/docs/architecture/4-runtime-view.md @@ -29,7 +29,7 @@ sequenceDiagram | External reference check | It will be checked if all exernal references are available in the TripleStore. The BAMM SDK does provide a mechanisim where the resolving against the TripleStore can be integrated. | -## Download of the documentation of an Aspect Model +### Download of the documentation of an Aspect Model ```mermaid sequenceDiagram actor ModelAdmin as Model Admin diff --git a/docs/architecture/5-deployment-view.md b/docs/architecture/5-deployment-view.md index f7eec26..e4d55dd 100644 --- a/docs/architecture/5-deployment-view.md +++ b/docs/architecture/5-deployment-view.md @@ -11,7 +11,7 @@ For Deployment needed: To deploy this system, you need to use the Helm Chart in a running Kubernetes cluster. The Helm Chart is located under "charts/semantic-hub". In case you don't have a running cluster, you can set up one by yourself -locally, using minikube. For further information checkout the [readme.md](https://github.com/eclipse-tractusx/sldt-semantic-hub/blob/main/README.md). +locally, using minikube. For further information checkout the [readme.md](../../README.md). and [install.md](../../INSTALL.md). ### NOTICE diff --git a/docs/architecture/6-concepts.md b/docs/architecture/6-crosscutting-concepts.md similarity index 75% rename from docs/architecture/6-concepts.md rename to docs/architecture/6-crosscutting-concepts.md index 451e2c1..12f8c8c 100644 --- a/docs/architecture/6-concepts.md +++ b/docs/architecture/6-crosscutting-concepts.md @@ -33,7 +33,7 @@ Release Status aux:releaseStatus aux:DRAFT . ``` -## Package +### Package | No | Rule | Example | |----|-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1. | A package is defined by the urn prefix until "#". | net.catenax.semantics.product:1.2.0# | @@ -43,6 +43,65 @@ Release Status | 5. | All aspect models and model elements scoped to a package have the same status. | Possible: net.catenax.semantics.product:1.2.0#ProductDescription → RELEASE, net.catenax.semantics.product:1.2.0#ProductUsage → RELEASE net.catenax.semantics.product:1.2.0#ProductDetails → RELEASE Not Possible: net.catenax.semantics.product:1.2.0#ProductDescription → RELEASE, net.catenax.semantics.product:1.2.0#ProductUsage → DRAFT | +### Security / Safety / Use of JWT Token + +The whole environment is secured with OAuth2. We used and recommend the usage of Keycloak. The Semantic hub has +a realm entry in Keycloak. Every user who wants to use Semantic Hub +need the corresponding roles for his user. + +The roles are: + +1. [ ] *VIEW*( "view_semantic_model" ) +2. [ ] *ADD*( "add_semantic_model" ) +3. [ ] *DELETE*( "delete_semantic_model" ) +4. [ ] *UPDATE*( "update_semantic_model" ) +These roles are sent within a JWT Token generated by Keycloak. + +With Add,Delete,Update roles it is possible to add or modify entries from the +Semantic Hub Database. For searching the view role is sufficient. +The credentials are set with entries in Helm Charts. + +### Authentication & Authorization +The service is secured by a OAuth2 compliant authorization. Every API call has to provide a +valid Bearer Token. Authorization is provided by a role based access. These roles are possible: + +| Role | Description | +|-------------------------|-------------------------------| +| view_semantic_model | can search for semantic model | +| add_semantic_model | can add semantic model | +| delete_semantic_model | can delete semantic model | +| update_semantic_model | can update semantic model | + + +### Security Assessment + +### Data Flow Diagram + +```mermaid +%%{init: {"flowchart": {"curve": "linear"} }}%% +flowchart LR + DC(Data Consumer) + DP(Data Provider) + K(Keycloak) + + subgraph Semantic Hub + SHB(Semantic Hub Backend) + SH[(Sematic Hub postgres)] + end + + SHB <-->|Find submodels / metadata| DC + SHB <-->|Submodel creation \n provide metadata| DP + + SHB <--> SH + + K -->|Public key for token validation| SHB + + DC <-->|Token request| K + DP <-->|Token request| K +``` + + + ### NOTICE This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/docs/architecture/documentation.md b/docs/architecture/documentation.md deleted file mode 100644 index 338b06c..0000000 --- a/docs/architecture/documentation.md +++ /dev/null @@ -1,150 +0,0 @@ -## Architectural Overview -The SLDT Semantic Hub stores Semantic Model definitions and allows the generation of several artifacts. It restricts access to the models by authentication via a token and authorization via roles in the token claims. Therefore, the Hub interacts with a Keycloak instance. The models are created in the Hub during our governance process as depicted below. -```mermaid -graph LR - SemanticHub[Semantic hub] -- "read models" --> Data[Data Consumer/Provider] - Keycloak --"PUB Key for token validation" --> SemanticHub - Github[Github Models Repository] -- "synchronize models from the governance process" --> SemanticHub -``` - -## Implementation -The following section describes the use cases implemented for the semantic hub. - -### Upload of an aspect model -```mermaid -sequenceDiagram - actor ModelAdmin as Model Admin - participant SemanticHub as Semantic hub - participant TripleStore as TripleStore - - ModelAdmin ->>+ SemanticHub: Upload aspect model file (.ttl) - loop validation - SemanticHub ->>+ SemanticHub: Check if aspect model is complaint with bamm/samm (using sdk) - SemanticHub ->>+ TripleStore: Check if aspect model already exists - Note over SemanticHub, TripleStore: If the aspect model exists and is in release status,
the upload will be rejected.
If the aspect model exists in draft status,
upload will be accepted. - SemanticHub ->>+ TripleStore: Check if external referenceses exists - Note over SemanticHub, TripleStore: If an external reference does not exists,
the upload will be rejected.
Should we allow to reference namespaces,
in DRAFT state? - TripleStore -->> SemanticHub: response ok - end - note over ModelAdmin, SemanticHub: The model admin provides the release status
(RELEASED/DRAFT) upon upload - SemanticHub ->>+ SemanticHub: Add the release status as triple to the model - SemanticHub ->>+ TripleStore: Write all triples to TripleStore - TripleStore -->> SemanticHub: response ok - SemanticHub -->> ModelAdmin: Response upload successful -``` - -| Validation | Description Value | -|---|---| -| BAMM compliance | Checks if the model is compliant with the BAMM. The BAMM SDK does provide the validation logic. | -| Model Status check (RELEASE vs DRAFT) | Uploads will always accepted when there are no existing namespace:version combination in the TripleStore. For a model in DRAFT state, uploads will always be accepted. For a model in RELEASE state, uploads will be denied. RELEASED models are immutable. | -| External reference check | It will be checked if all exernal references are available in the TripleStore. The BAMM SDK does provide a mechanisim where the resolving against the TripleStore can be integrated. | - - - -## Example: -Example Aspect Model -``` -@prefix xsd: . -@prefix bamm: . -@prefix : . - - -:DocumentationSimple a bamm:Aspect; -bamm:name "ManufacturerDocumentationSimple"; -bamm:preferredName "ManufacturerDocumentation"@en; -bamm:description "The Submodel defines a simplified set of manufacturer documentation to bring about information from manufacturer to operator of industrial equipment."@en; - -:documents a bamm:Property; -bamm:name "documents"; -bamm:preferredName "documents"@en; -bamm:description "Set of documents"@en; -``` - -The Semantic Hub will add the release status as triple upon upload: -Release Status -``` -@prefix aux: - - aux:releaseStatus aux:DRAFT . -``` - -## Package -| No | Rule | Example | -|----|-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 1. | A package is defined by the urn prefix until "#". | net.catenax.semantics.product:1.2.0# | -| 2. | A package can contain one or multiple aspects. | Example 1: net.catenax.semantics.traceability:1.2.0#Traceability Example 2: net.catenax.semantics.product:1.2.0#ProductDescription net.catenax.semantics.product:1.2.0#ProductUsage net.catenax.semantics.product:1.2.0#ProductDetails | -| 3. | Multiple versions of a package can exists. | Possible: net.catenax.semantics.product:1.2.0 net.catenax.semantics.product:4.2.0 | -| 4. | The versioning applies to the package. All aspects and model elements scoped to a package have the same version. | Possible: net.catenax.semantics.product:1.2.0#ProductDescription net.catenax.semantics.product:1.2.0#ProductUsage net.catenax.semantics.product:1.2.0#ProductDetails Possible:net.catenax.semantics.product:4.3.0#ProductDescription net.catenax.semantics.product:4.3.0#ProductUsage net.catenax.semantics.product:4.3.0#ProductDetails Not Possible: net.catenax.semantics.product:1.3.0#ProductDescription net.catenax.semantics.product:1.2.0#ProductUsage net.catenax.semantics.product:3.2.0#ProductDetails | -| 5. | All aspect models and model elements scoped to a package have the same status. | Possible: net.catenax.semantics.product:1.2.0#ProductDescription → RELEASE, net.catenax.semantics.product:1.2.0#ProductUsage → RELEASE net.catenax.semantics.product:1.2.0#ProductDetails → RELEASE Not Possible: net.catenax.semantics.product:1.2.0#ProductDescription → RELEASE, net.catenax.semantics.product:1.2.0#ProductUsage → DRAFT | - -## Download of the documentation of an Aspect Model -```mermaid -sequenceDiagram - actor ModelAdmin as Model Admin - participant SemanticHub as Semantic hub - participant TripleStore as TripleStore - - ModelAdmin ->>+ SemanticHub: Get documentation for aspect model com.catenax:0.0.1:Sample - SemanticHub ->>+ TripleStore: Resolve aspect model with all references based on provided urn com.catenax:0.0.1:Sample - TripleStore -->> SemanticHub: response - SemanticHub ->>+ SemanticHub: generate documentation based on the response from TripleStore - SemanticHub -->> ModelAdmin: respond with generated documenation -``` - -Example queries to resolve an aspect model with all references: -Construct Query -``` -@prefix ns: - -CONSTRUCT { -?s ?p ?o . -} WHERE { -bind( ns: as ?aspect) -?aspect (<>|!<>)* ?s . // resolves all references -?s ?p ?o . -} -Search for Aspect Models -The current search API can stay as is. Below is an example query for selecting bamm properties: -Search Queries -CONSTRUCT { -?s ?p ?o . -} WHERE { -FILTER ( $param == ?o ) // Custom filter can be added here. -?s ?p ?o . -} -``` -## Security Assessment - -### Data Flow Diagram - -```mermaid -%%{init: {"flowchart": {"curve": "linear"} }}%% -flowchart LR - DC(Data Consumer) - DP(Data Provider) - K(Keycloak) - - subgraph Semantic Hub - SHB(Semantic Hub Backend) - SH[(Sematic Hub postgres)] - end - - SHB <-->|Find submodels / metadata| DC - SHB <-->|Submodel creation \n provide metadata| DP - - SHB <--> SH - - K -->|Public key for token validation| SHB - - DC <-->|Token request| K - DP <-->|Token request| K -``` - -### NOTICE - -This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). - -- SPDX-License-Identifier: Apache-2.0 -- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH -- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation -- Source URL: https://github.com/eclipse-tractusx/sldt-semantic-hub.git diff --git a/docs/architecture/glossary.md b/docs/architecture/glossary.md index f9c0544..a6a7d84 100644 --- a/docs/architecture/glossary.md +++ b/docs/architecture/glossary.md @@ -4,7 +4,7 @@ |----------|------------------------------------------------------------------------------------------------------------| | Keycloak | Keycloack is an open-source Identity Management and Access management solution that allows Single Sign-On. | | Realm | Manages a set of users, credentials, roles. Authenticates the users it controls. | -| SAMM | Semantic Aspect Meta Model | +| SAMM | Semantic Aspect Meta Model | ### NOTICE This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). From 906964f9f0af5d9fa49b386e721ddd72be1ecf9f Mon Sep 17 00:00:00 2001 From: Sahil Aggarwal Date: Mon, 18 Nov 2024 10:39:32 +0100 Subject: [PATCH 5/5] Added README.md file --- docs/README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8b1c63f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,26 @@ + + +# Introduction +Following documentation is available: + +| Documentation | Purpose | +|------------------------------------------|--------------------------------------------------| +| [Arc42](architecture/) | Architecture documentation for the Semantic Hub. | \ No newline at end of file