# FY25_SDK_for_Semantics

本リポジトリは2025年 SDK「SDK for Semantics」の開発のリポジトリです。

- [FY25\_SDK\_for\_Semantics](#fy25_sdk_for_semantics)
  - [構成](#構成)
  - [概要​](#概要)
    - [RDF定義](#rdf定義)
      - [SAMMによるセマンティック定義](#sammによるセマンティック定義)
      - [SAMMの拡張](#sammの拡張)
    - [RDFファイル構成](#rdfファイル構成)
  - [Discovery Serviceへの登録](#discovery-serviceへの登録)
    - [SDKの使い方](#sdkの使い方)
    - [環境構築方法](#環境構築方法)
      - [前提条件](#前提条件)
      - [手順](#手順)
      - [停止](#停止)
    - [SDK使用例](#sdk使用例)
    - [WebサービスのRDFの定義例](#webサービスのrdfの定義例)
  - [バージョンアップなどでI/Fを編集する場合の手順](#バージョンアップなどでifを編集する場合の手順)
  - [注意事項](#注意事項)

## 構成

```text
├─Documents                      # 設計書
│  └─WebServiceAspectModel       # Webサービス用Aspect Model
│      └─UASL_AspectModel        # UASLを使ったAspect Modelの例
└─SDK                            # SDKソース、ツール
   ├─WEB_TOOL                    # WEBアプリツール
   └─CLI_TOOL                    # CLIツール
```

## 概要​

### RDF定義

本プロジェクトでは、Discovery Serviceに登録するWebサービスをRDFで定義し、検索したWebサービスのAPIをRDFにて取得可能にする。

#### SAMMによるセマンティック定義

WebサービスのRDF定義は、Eclipse ESMF の **SAMM（Semantic Aspect Meta Model）** をベースとしたセマンティックな定義を採用している。
SAMM は、デジタルツインのAspect Modelを標準化された方法で記述するためのメタモデルであり、データの意味（セマンティクス）と構造を機械可読な形で定義できる。

- SAMM仕様: <https://eclipse-esmf.github.io/samm-specification/snapshot/index.html>
- SAMM CLI / Aspect Model Editor: <https://eclipse-esmf.github.io/ame-guide/introduction.html>

#### SAMMの拡張

SAMMの標準仕様ではREST APIの呼び出し方（HTTPメソッド、パス、クエリパラメータ、レスポンスのHTTPステータスコード等）を定義する手段がないため、W3C標準のボキャブラリ（`http:`, `hydra:`, `dcterms:`, `dcat:`等）を組み合わせてAPI定義を拡張している。

### RDFファイル構成

RDFによるWebサービスの定義は以下の3種類のファイルで構成される。

| ファイル種別               | 説明                                                                                                  |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
| Aspect Modelファイル       | SAMMの規定に従い、Webサービス自体をAspect Modelとして定義する。Aspect Model Editorで編集・参照可能。  |
| WebサービスAPI定義ファイル | Aspect Modelでは表現できないREST API / JSON-RPCの呼び出し方やWebサービスのクラス定義をRDFで定義する。 |
| インスタンスファイル       | デプロイしたWebサービスの実体（エンドポイントURL等の環境固有情報）をインスタンスとして定義する。      |

REST IFとJSON-RPCの両方に対応しており、それぞれのプロトコル用にAPI定義ファイルおよびインスタンスファイルの仕様が定められている。

詳細は [Documents/WebServiceAspectModel/WebService定義TTL仕様.md](Documents/WebServiceAspectModel/WebService定義TTL仕様.md) を参照。

## Discovery Serviceへの登録

運営事業者が自社のWebサービスをDiscovery Srviceに公開するには、以下の手順が必要になる。

- 公開するWebサービスをRDFにて定義する。
  - RDFのうちAspect ModelはSAMMにより定義されるので、Eclipse ESMFの提供する[Aspect Model Editor](https://eclipse-esmf.github.io/ame-guide/introduction.html)を使ってGUIで編集可能
- ​Discovery SrviceのAPIを使用し、WebサービスのRDFを登録する。

上記の作業を容易にするため、本プロジェクトではSDK（ツール）を提供する。

### SDKの使い方

SDKには、以下の２種類のツールが含まれる。

- WEB_TOOL : WebアプリとしてDiscovery Serviceへの登録機能を提供したもの。Web上からCLI_TOOLを操作する。
  - 使用方法： [Documents/WebServiceAspectModel/WebService定義TTL仕様.md](Documents/WebServiceAspectModel/WebService定義TTL仕様.md) を参照
- CLI_TOOL ： RDFファイルの作成をサポートするコンソール用のツール
  - インスタンステンプレート生成ツール : Aspect ModelとAPI定義のTTLファイルからWebサービスのインスタンスファイルのテンプレートを生成するツール
  - TTL検証ツール : RDF（TTLファイル）の検証をするツール
  - RDF to JSON-LD 変換ツール： TTLファイル形式のインスタンスファイルをDiscovery Serviceに登録するJSON-LD形式に変換するツール
  - SAMM CLI ラッパー ： Eclipse ESMFの[SAMM CLI](https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/samm-cli.html)を使用するためのラッパー

### 環境構築方法

WEB_TOOLはDocker Composeを使用して構築する。

#### 前提条件

- Docker および Docker Compose がインストールされていること

#### 手順

1. 環境変数ファイルを作成する

   ```bash
   cd SDK/WEB_TOOL
   cp sample.env .env
   ```

2. `.env` ファイルを編集し、Discovery ServiceおよびDiscovery FinderのURLを設定する

   ```env
   DISCOVERY_SERVICE_URL=http://discovery.XXX.XXX.XXX
   FINDER_SERVICE_URL=http://finder.XXX.XXX.XXX
   ```

3. Docker Composeでビルド・起動する

   ```bash
   docker compose up -d --build
   ```

4. ブラウザで `http://localhost:5000` にアクセスする

#### 停止

```bash
docker compose down
```

### SDK使用例

- WEB_TOOLを起動する。
- WEB_TOOLのURLにブラウザでアクセスする。

### WebサービスのRDFの定義例

ドローン航路システムを例としたRDFの定義例： [Documents/WebServiceAspectModel/UASL_AspectModel](Documents/WebServiceAspectModel/UASL_AspectModel)

## バージョンアップなどでI/Fを編集する場合の手順

- APIの追加・削除・更新が発生した場合
  - APIの追加・削除・更新に合わせてAspect ModelファイルとWebサービスAPI定義ファイルを更新する。
  - Aspect Modelで使用しているName spaceを更新する。
    - 例： ver.1.2.0からver.1.3.0に更新する。`@prefix : <urn:samm:com.uasl.service:1.2.0#> .` → `@prefix : <urn:samm:com.uasl.service:1.3.0#> .`
  - 更新したAspect ModelファイルとWebサービスAPI定義ファイルを公開する。
  - インスタンスファイルを更新する。
  - SDKを使って更新したインスタンスファイルをDiscovery Serviceに登録する。

## 注意事項

- 本プロジェクトで使用している外部の仕様・ツール・ライブラリの著作権および商標は、それぞれの権利者に帰属します。
- 使用している主な外部仕様・ツールのライセンスは以下の通りです。

| 外部仕様・ツール                                             | ライセンス                           | 参照先                                                                                           |
| ------------------------------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| Eclipse ESMF SAMM（SAMM仕様・SAMM CLI・Aspect Model Editor） | Mozilla Public License 2.0 (MPL-2.0) | <https://github.com/eclipse-esmf/esmf-sdk/blob/main/LICENSE>                                     |
| W3C仕様（HTTP-in-RDF, Hydra, DCAT等）                        | W3C Software and Document License    | <https://www.w3.org/copyright/software-license-2023/>                                            |
| RDFLib                                                       | BSD 3-Clause License                 | <https://github.com/RDFLib/rdflib/blob/main/LICENSE>                                             |
| PyLD                                                         | BSD 3-Clause License                 | <https://github.com/digitalbazaar/pyld/blob/main/LICENSE>                                        |
| Flask                                                        | BSD 3-Clause License                 | <https://github.com/pallets/flask/blob/main/LICENSE.txt>                                         |
| Gunicorn                                                     | MIT License                          | <https://github.com/benoitc/gunicorn/blob/master/LICENSE>                                        |

## ライセンス
- 本リポジトリはMITライセンスで提供されています。
- ソースコードおよび関連ドキュメントの著作権はIntent Exchange株式会社に帰属します。

## 免責事項
- 本リポジトリの内容は予告なく変更・削除する可能性があります。
- 本リポジトリの利用により生じた損失及び損害等について、いかなる責任も負わないものとします。