# 第6章　共通スキーマ設計——全APIの「共通言語」

> **ナビゲーション**
>
> * 前の章: [第5章　5層アーキテクチャ](/ja/solutions/part3-architecture/ch05-layered-architecture.md)
> * 次の章: [第7章　ベンダー地図](/ja/solutions/part4-procurement/ch07-vendor-landscape.md)

***

![第6章：共通スキーマ設計——全APIを統合・制御する「共通言語」の構築](/files/F6J9nixVuaDKfc5kUOlI)

***

「スキーマ（Schema）」とは「構造の設計図」のことです。APIがどのようなデータを受け取り、どのような形式で返すかを定義したものです。言語APIには数十のベンダーが存在し、それぞれが独自のスキーマを持っています。本章では、それらを統一的に扱うための「共通スキーマ」を設計します。

***

## 6.1 なぜ共通スキーマが必要か

### バラバラなベンダー仕様という問題

異なるベンダーのAPIを並べて比べると、同じ「翻訳リクエスト」でもフィールド名がまったく違います。

```json
// ベンダーA の形式
{ "q": "こんにちは", "source": "ja", "target": "en" }

// ベンダーB の形式
{ "text": "こんにちは", "from_lang": "ja", "to_lang": "en" }

// ベンダーC の形式
{ "content": "こんにちは", "sourceLang": "JA", "targetLang": "EN-US" }
```

このままでは、ベンダーを切り替えるたびに呼び出しコードを書き直す必要があります。コスト比較や冗長化（一方が障害を起こしたときのフェイルオーバー）も困難です。

![各社バラバラなAPI仕様が、冗長化やコスト比較を困難にしている——ベンダー切り替えのたびにコードの書き換えが発生し、運用コストが肥大化する](/files/LxvuX5gHQ18Ly3nHOy2u)

### 共通スキーマという解決策

共通スキーマとは、**すべてのベンダーAPIを呼び出す前段に置く「共通の窓口」が使う統一フォーマット**です。外部の世界は常にこの共通スキーマでリクエストを送り、ゲートウェイ（第7章で詳述）が各ベンダーの形式へ変換（アダプテーション）します。

```
利用者 → [共通スキーマ形式] → ゲートウェイ → [ベンダー固有形式] → ベンダーAPI
```

![共通スキーマの導入により、全ベンダーのAPIを単一の仕様で統合・制御できる——呼び出しコードの書き換えゼロ・自動フェイルオーバー・コスト比較の容易化を実現](/files/APGBdfuVo33V8Kjm2pkK)

### OpenAPI / JSON Schemaとの関係

共通スキーマは **JSON Schema** で型を定義し、**OpenAPI Specification** でAPIエンドポイントと組み合わせて文書化します。これにより：

* 自動バリデーション（型チェック、必須フィールド確認）
* SDKの自動生成
* インタラクティブなドキュメント（Swagger UIなど）

が実現します。本章で定義する型はすべてJSON Schemaの書き方に準拠しています。

![ゲートウェイ前段にJSON Schema準拠の共通窓口を置き、自動バリデーション・SDK自動生成・インタラクティブドキュメントを実現する](/files/FPBCJZ6bl9L52QOmZUTZ)

***

## 6.2 コア型の定義

### ContentObject——処理対象のコンテンツ

翻訳や音声認識の「処理対象」を表す型です。テキストだけでなく、音声・ドキュメント・画像も統一的に表現できます。

```json
{
  "type": "text | audio | document | image",
  "value": "翻訳したいテキスト or base64エンコードされたファイル",
  "format": "plain | html | markdown | pdf | docx",
  "encoding": "utf-8"
}
```

| フィールド      | 型   | 説明                                                  |
| ---------- | --- | --------------------------------------------------- |
| `type`     | 文字列 | コンテンツの種別（text / audio / document / image）           |
| `value`    | 文字列 | 本文テキスト、またはファイルのBase64エンコード文字列                       |
| `format`   | 文字列 | テキストなら plain / html / markdown、ファイルなら pdf / docx など |
| `encoding` | 文字列 | 文字エンコーディング（テキスト型のみ。通常は "utf-8"）                     |

![テキストから画像まで、あらゆる処理対象をBase64変換で統一フォーマット化する——ContentObjectのフィールド構造と非テキストデータのJSON統合](/files/UkbFh3uSWyIf7Ktdb1WN)

> **Base64（ベース64）とは**：バイナリファイル（音声・画像など）をテキストとして送信できるようにする変換方式です。JSONはテキスト形式のため、ファイルを直接埋め込めません。Base64に変換することで文字列として扱えます。

***

### LanguageCode——言語コード

言語を表す文字列は **BCP-47** という国際標準に従います。

| コード例      | 意味           |
| --------- | ------------ |
| `"ja"`    | 日本語          |
| `"en"`    | 英語（地域不問）     |
| `"en-US"` | アメリカ英語       |
| `"en-GB"` | イギリス英語       |
| `"zh-TW"` | 繁体字中国語（台湾）   |
| `"zh-CN"` | 簡体字中国語（中国大陸） |

#### 言語コードの落とし穴

「中国語」と一口に言っても、繁体字（`zh-TW`）と簡体字（`zh-CN`）は文字体系が異なります。`"zh"` だけを指定すると、ベンダーによって解釈が異なり予期しない結果になります。また「ポルトガル語」にもブラジル（`pt-BR`）とポルトガル（`pt-PT`）があります。

> **原則：地域バリアントがある言語は、必ずサブタグ（`-XX` 部分）まで指定する**

![言語指定はBCP-47に準拠し、地域バリアントの予期せぬ解釈を防ぐため必ずサブタグを指定する——Pitfall（zh のブラックボックス）vs Best Practice（zh-TW / zh-CN / pt-BR / pt-PT）](/files/YW3BxwPMwJqPEJclyOER)

***

### QualityTier——品質ティア

第4章で学んだ品質ティアを、APIスキーマ内で表現する型です。

```
"mt" | "mtpe" | "ait" | "expert_in_the_loop"
```

| 値                      | 意味                                                                 |
| ---------------------- | ------------------------------------------------------------------ |
| `"mt"`                 | 機械翻訳のみ。人間レビューなし                                                    |
| `"mtpe"`               | MTポストエディット。MTの出力を人間が確認・修正する（軽微〜完全の幅あり）                             |
| `"ait"`                | AI翻訳。著者が文書要件をAIに指示し、ターゲット言語の文書を直接生成                                |
| `"expert_in_the_loop"` | エキスパート検証付きAIT。AITで生成した文書を言語専門家がcertification/verificationする最高品質レベル |

![4段階の品質ティアを定義し、要件に応じたベンダーやワークフローの自動選択を可能にする——mt → mtpe → ait → expert\_in\_the\_loop のステップと各ティアの概要](/files/fzK1oMOBHIfkW0c9sJsU)

このフィールドを指定することで、ゲートウェイは適切なベンダーやワークフローを自動選択できます。

***

### JobStatus——ジョブステータス

非同期処理（第5章 L2参照）のジョブが現在どの状態にあるかを表す型です。

```
"pending" | "processing" | "completed" | "failed" | "cancelled"
```

| 値              | 意味                     |
| -------------- | ---------------------- |
| `"pending"`    | キューに入っており、まだ処理が始まっていない |
| `"processing"` | 現在処理中                  |
| `"completed"`  | 処理が正常に完了した             |
| `"failed"`     | エラーにより処理が失敗した          |
| `"cancelled"`  | 利用者またはシステムによりキャンセルされた  |

ステータスの遷移は一方向で、`completed` や `failed`、`cancelled` になったジョブを `pending` に戻すことは通常できません（再試行が必要な場合は新しいジョブを発行します）。

![非同期ジョブのステータスは一方向へ遷移し、後戻りはしない——pending → processing → completed / failed / cancelled、再試行は新規ジョブとして発行](/files/hlt4GkAYCod3y3lxip1B)

***

### ErrorObject——エラー情報

APIがエラーを返すとき、その原因を機械が読めるコードと人間が読めるメッセージの両方で伝えます。

```json
{
  "code": "UNSUPPORTED_LANGUAGE_PAIR",
  "message": "指定された言語ペアはサポートされていません",
  "details": { "source": "ja", "target": "sw" }
}
```

| フィールド     | 説明                              |
| --------- | ------------------------------- |
| `code`    | 大文字スネークケースのエラー識別子。プログラムによる分岐に使う |
| `message` | 人間が読んで理解できるエラー説明文               |
| `details` | エラーの詳細情報。デバッグや自動回復ロジックで活用する     |

> \*\*`"sw"` はスワヒリ語の言語コードです。\*\*日本語→スワヒリ語の翻訳に対応していないベンダーは上記のようなエラーを返します。

エラーコードを標準化することで、ゲートウェイが「このエラーなら別ベンダーにフォールバックする」というロジックを実装できます。

![エラーコードの標準化により、別ベンダーへの自動フォールバックが実装可能になる——ErrorObjectの解剖とFallback Flowchart（UNSUPPORTED\_LANGUAGE → Vendor B へ自動ルーティング）](/files/qPRvByW8Nlr9jEWqX9kS)

***

## 6.3 リクエスト骨格の標準パターン

ここまでのコア型を組み合わせた、「標準リクエスト」の完全な例を示します。この形式が、すべての言語APIサービスに共通するリクエスト骨格です。

```json
{
  "content": {
    "type": "text",
    "value": "本製品の使用前に必ず取扱説明書をお読みください。",
    "format": "plain"
  },
  "source_language": "ja",
  "target_language": "en",
  "domain": "technical",
  "quality_tier": "mtpe",
  "context": {
    "glossary_id": "gloss_technical_001",
    "tm_id": "tm_product_manual",
    "style_guide_id": "style_formal_en"
  },
  "options": {
    "preserve_formatting": true,
    "formality": "formal"
  }
}
```

### contextオブジェクト——「知識」の注入

`context` フィールドは第5章L3（品質・知識層）の資産をAPIリクエストに接続するための仕組みです。

| フィールド            | 説明                           |
| ---------------- | ---------------------------- |
| `glossary_id`    | 使用する用語集のID。固有名詞・専門用語を統一する    |
| `tm_id`          | 使用する翻訳メモリのID。過去の翻訳資産を再利用する   |
| `style_guide_id` | 使用するスタイルガイドのID。文体・表記ルールを適用する |

これらのIDは事前にシステムへ登録しておいたリソースを参照します。IDを差し替えるだけで「このプロジェクトでは法律用語集を使う」「あのプロジェクトではカジュアルなスタイルで」と切り替えられます。

![用語集や翻訳メモリなどの資産はID参照で注入し、プロジェクトごとの柔軟な切り替えを実現する——Context ObjectへのID接続とLegal Project / Marketing Projectの切り替え例](/files/Yx9tIlBWwu8h4etL3mnL)

### optionsオブジェクト——任意パラメータの設計方針

`options` は必須ではない調整パラメータを格納します。設計上の重要な原則として、**コアパラメータとオプションパラメータを分離する**ことが挙げられます。

* コア（必須）：`content`・`source_language`・`target_language`
* オプション：`domain`・`quality_tier`・`context`・`options`

オプションフィールドが省略された場合は、合理的なデフォルト値が適用されます。これにより、シンプルな利用ケースではリクエストを最小化でき、高度な利用ケースでは細かく制御できます。

![APIリクエストは「必須コアパラメータ」と「任意オプション」を明確に分離して設計する——省略時は合理的なデフォルト値を適用し、シンプルな利用ケースでのリクエストを最小化](/files/2paaFU3VXEPoM5v8r8Cb)

### バージョニング戦略

APIスキーマは時間とともに変化します。後方互換性を保ちながら変更を導入するための主要な戦略が2つあります。

| 戦略             | 例                                     | 特徴                            |
| -------------- | ------------------------------------- | ----------------------------- |
| **URLパスバージョン** | `/v1/translations`・`/v2/translations` | シンプルで分かりやすい。ブラウザやキャッシュとの相性が良い |
| **ヘッダーバージョン**  | `API-Version: 2024-01-01`             | URLを汚染しない。日付ベースで変更履歴が追いやすい    |

本書では、可視性と管理のしやすさから **URLパスバージョン**を推奨します。新しいバージョンを追加するときは、旧バージョンを少なくとも12ヶ月間は並行提供し、移行期間を確保しましょう。

![バージョニングはURLパス型を推奨し、旧バージョンの12ヶ月並行稼働で安全な移行を担保する](/files/NK9RNRlnw25k2HzH2tBV)

***

## まとめ

![5つのコア型と標準リクエスト骨格が組み合わさり、堅牢なAPIゲートウェイの基盤となる——Common Schema Foundation（ContentObject / LanguageCode / QualityTier / JobStatus / ErrorObject）](/files/8r5tENtlv55fjZsVWRbw)

共通スキーマはAPIゲートウェイの基盤であり、ベンダー切り替え・フォールバック・コスト最適化を可能にするインフラです。本章で定義した `ContentObject`・`LanguageCode`・`QualityTier`・`JobStatus`・`ErrorObject` の5つのコア型と標準リクエスト骨格が、後続章で構築するゲートウェイ設計の共通言語になります。

![共通言語の設計を完了し、次はリクエストを各ベンダーへ分配するゲートウェイの構築に進む——第7章：APIゲートウェイの設計・実装へ](/files/CU9lA5DlGcMe0proKocd)

***

→ [第7章 APIゲートウェイ設計](https://github.com/kawanohiroki/language-api-world/blob/main/part3-architecture/ch07-api-gateway.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://translationlab.gitbook.io/ja/solutions/part3-architecture/ch06-common-schema.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.