各種 API ドキュメント、セキュリティスキャンツール、CI/CD パイプラインのログを読んでいる際に、Manifest、Report、Finding、Evidence といった用語をよく見かけませんか？これらは特定のプログラミング言語の構文ではなく、業界で一般的に使われている データ階層の慣用用語 です。これらの用語にはどのような意味があるのでしょうか？
核心概念：「健康診断」で理解するデータ階層
病院での 健康診断 の流れに例えるとわかりやすいでしょう。これら 4 つの用語は、高レベルのサマリーから最下層の生データまでのデータ階層に正確に対応しています。
| 用語 | 健康診断での例え | ソフトウェアアーキテクチャでの対応説明 |
|---|---|---|
Manifest |
健診受付票 | 実行項目、バージョン、環境設定を宣言する記述的メタデータ。 |
Report |
健診結果報告書 | 実行完了後の完全なサマリー。全体ステータスと監査結果を含む。 |
Finding |
報告書の赤字注記 | 報告書内で特定された発見事項（例：「高血圧の検出」やセキュリティ脆弱性）。 |
Evidence |
血圧計の測定紙 | 発見事項を裏付ける一次客観証拠（ログ記録やデータ測定値）。 |
これらの用語はプログラミング言語の予約語ではなく、業界共通のデータモデルです。
Mermaid ダイアグラムを使用して、これら 4 つのデータ構造における上下関係と包含関係を視覚化できます：
graph TD
A["Manifest (実行仕様/メタデータ)"] -->|スコープ定義と実行| B["Report (完全サマリー報告)"]
B -->|複数含む| C["Finding (具体的発見/観察)"]
C -->|複数関連付け| D["Evidence (客観的生証拠)"]
なぜ層分離設計が必要なのか？データ階層の 3 大メリット
なぜデータを単一の巨大な JSON にまとめず細かく分割するのでしょうか？この設計にはいくつかの大きなメリットがあります：
優れた API アーキテクチャ設計は、フロントエンドの描画をスムーズにし、データの信頼性と拡張性を高めます。
| メリット | 説明 |
|---|---|
| 関心の分離 | フロントエンドはまず Finding の概要を読み込み、詳細が必要な時のみ巨大な Evidence を取得できます。 |
| 高い信頼性 | 一次証拠 Evidence を提供することで Finding が誤検知でないことを証明し、システムの監査可能性を大幅に向上させます。 |
| 柔軟な拡張性 | 既存のスキーマを壊すことなく、1 つの Finding に複数の Evidence を柔軟に関連付けられます。 |
その他の一般的な用語：Metadata、Artifact、Payload
4 つのコア階層に加え、API 設計、パイプライン構築、ペイロード定義で頻繁に登場する 3 つの重要用語 Metadata、Artifact、Payload の役割を整理します：
| 用語 | 核心的定義 | 日常生活での例え | ソフトウェアアーキテクチャの実際例 |
|---|---|---|---|
Metadata |
データ自体を説明するデータ | 小包の送り状ラベル、写真の EXIF 情報 | HTTP Header、リクエストタイムスタンプ timestamp、ページネーション情報 page。 |
Artifact |
プロセス実行後に生成される実体成果物 | 工場で生産された自動車、健診 CD | ビルドされた .apk ファイル、Docker Image、監査 PDF レポート。 |
Payload |
伝送における中心的なビジネスデータ | 小包の箱の中に実際に入っているスマートフォン | HTTP POST Body 内の JSON ビジネス本体コンテンツ。 |
Payloadは郵送小包の中身 であり、Metadataは外側に貼られた配送ラベル のようなものです。
これら 3 つの連携方法を理解するために、典型的な API Request データ構造を見てみましょう：
{
"metadata": {
"version": "v1.2.0",
"timestamp": "2026-08-02T15:08:41Z",
"request_id": "req-98765"
},
"payload": {
"report_id": "REP-2026-001",
"status": "COMPLETED",
"artifact_url": "https://example.com/artifacts/build-report.pdf"
}
}
この JSON の例では：
metadataは伝送と環境のコンテキスト（バージョン、タイムスタンプ、リクエスト ID）を提供します。payloadは実際に伝送されるビジネスロジックデータ（レポート ID、ステータス）を含みます。artifact_urlはビルドタスクによって生成された実体ファイル（Artifact）を指し示します。
共通言語の力：システム間コミュニケーションの架け橋
異なるツールやチームが共通のデータモデル（例：Report -> Findings -> Evidence）を採用することで、チーム間のコミュニケーションコストが劇的に削減されます。
CI/CD ツールが生成した Report をセキュリティスキャナーにそのままシームレスに渡して解析する—これが共通言語による統合の強みです。
sequenceDiagram
autonumber
actor CI as CI/CD パイプライン
participant Scanner as セキュリティスキャナー
participant Dashboard as 管理ダッシュボード
CI->>Scanner: Manifest を提供してスキャン実行
Scanner->>Scanner: Report と Findings を生成
Scanner->>Dashboard: 構造化 Payload (Finding + Evidence) を送信
Dashboard-->>CI: 監査結果を表示
まとめ
これらの用語の目的は、大規模システム間における データコミュニケーションと構造化 の課題を解決することにあります。
システム連携や API 設計の際には、これらのデータ階層の概念を Payload 構造に取り入れ、よりプロフェッショナルで拡張性の高いアーキテクチャを実現しましょう！