Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix:Updated documentation #306

Merged
merged 5 commits into from
Nov 18, 2024
Merged

Fix:Updated documentation #306

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f3a5122
updated documentation
agg3fe Nov 13, 2024
0bc0989
updated documentation
agg3fe Nov 13, 2024
62500e6
updated documentation
agg3fe Nov 13, 2024
5663d40
updated documentation
agg3fe Nov 17, 2024
906964f
Added README.md file
agg3fe Nov 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
26 changes: 26 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<!--
* Copyright (c) 2024 Robert Bosch Manufacturing Solutions GmbH
* Copyright (c) 2024 Contributors to the Eclipse Foundation
*
* See the NOTICE file(s) distributed with this work for additional
* information regarding copyright ownership.
*
* This program and the accompanying materials are made available under the
* terms of the Apache License, Version 2.0 which is available at
* https://www.apache.org/licenses/LICENSE-2.0.
*
* 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: Apache-2.0
-->

# Introduction
Following documentation is available:

| Documentation | Purpose |
|------------------------------------------|--------------------------------------------------|
| [Arc42](architecture/) | Architecture documentation for the Semantic Hub. |
14 changes: 14 additions & 0 deletions docs/architecture/1-introduction-and-goals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions docs/architecture/2-architecture-constraints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
41 changes: 41 additions & 0 deletions docs/architecture/3-system-scope-and-context.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
## 3 System scope and context

### Business Context

```mermaid
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).

- 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
79 changes: 79 additions & 0 deletions docs/architecture/4-runtime-view.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
## 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, <br> the upload will be rejected. <br>If the aspect model exists in draft status,<br> upload will be accepted.
SemanticHub ->>+ TripleStore: Check if external referenceses exists
Note over SemanticHub, TripleStore: If an external reference does not exists,<br> the upload will be rejected.<br>Should we allow to reference namespaces,<br> in DRAFT state?
TripleStore -->> SemanticHub: response ok
end
note over ModelAdmin, SemanticHub: The model admin provides the release status <br> (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: <urn:bamm:org.idtwin:1.0.0#DocumentationSimple>

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
24 changes: 24 additions & 0 deletions docs/architecture/5-deployment-view.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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](../../README.md). and [install.md](../../INSTALL.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-semantic-hub.git
118 changes: 40 additions & 78 deletions docs/documentation.md → docs/architecture/6-crosscutting-concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,47 +1,12 @@
## 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.
## 6 Concept

### 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, <br> the upload will be rejected. <br>If the aspect model exists in draft status,<br> upload will be accepted.
SemanticHub ->>+ TripleStore: Check if external referenceses exists
Note over SemanticHub, TripleStore: If an external reference does not exists,<br> the upload will be rejected.<br>Should we allow to reference namespaces,<br> in DRAFT state?
TripleStore -->> SemanticHub: response ok
end
note over ModelAdmin, SemanticHub: The model admin provides the release status <br> (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
```
### Overall Concept

| 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. |
#The overall concept can be found under **2 Architecture and
constraints**.

### Semantic Hub


## Example:
Example Aspect Model
```
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
Expand All @@ -68,7 +33,7 @@ Release Status
<urn:bamm:org.idtwin:1.0.0#> 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# |
Expand All @@ -77,43 +42,38 @@ Release Status
| 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: <urn:bamm:org.idtwin:1.0.0#DocumentationSimple>

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
### 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

Expand All @@ -140,11 +100,13 @@ flowchart LR
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
- Source URL: https://github.com/eclipse-tractusx/sldt-semantic-hub.git
Loading
Loading