TypeScriptを使っていて、型定義をJSONスキーマに変換したいなという場面がありました。この記事では、TypeScriptの型定義からJSONスキーマを生成するための主要な方法について解説します。
はじめに：TypeScript型からJSONスキーマへの変換が必要になるとき
TypeScriptの型定義は、開発時にコードの型安全性を確保するための強力なツールです。一方、JSONスキーマは、JSONデータの構造を検証するための標準的な仕様です。以下のような場面で、TypeScript型からJSONスキーマへの変換が役立ちます：
- APIのリクエスト/レスポンスの検証
- フォームデータのバリデーション
- データベースのスキーマ定義
- 設定ファイルの検証
変換方法の選択肢
TypeScript型からJSONスキーマへの変換には、主に3つの方法があります。それぞれの特徴を見ていきましょう。
1. typescript-json-schema：シンプルで軽量な選択肢
typescript-json-schemaは、基本的な機能に特化した軽量なツールです。小規模なプロジェクトや、シンプルな型定義の変換に向いています。
インストールは以下のコマンドで行います：
npm install typescript-json-schema --save-dev
基本的な使用例：
// ユーザー情報を定義する型
interface User {
name: string; // ユーザー名
age: number; // 年齢
email?: string; // メールアドレス（省略可能）
}
// コマンドラインでの変換実行
// npx typescript-json-schema ./src/types.ts User --out schema.json
生成されるJSONスキーマ：
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number"
},
"email": {
"type": "string"
}
},
"required": ["name", "age"]
}
2. ts-json-schema-generator：より完全な機能を持つ選択肢
ts-json-schema-generatorは、より多くの機能を備えた本格的なツールです。複雑な型定義や大規模プロジェクトでの使用に適しています。
インストール方法：
npm install ts-json-schema-generator --save-dev
JavaScript/TypeScriptでの使用例：
import { createGenerator } from 'ts-json-schema-generator';
// 設定オブジェクトの準備
const config = {
path: './src/types.ts', // 型定義ファイルのパス
type: 'User', // 変換したい型の名前
jsDoc: true // JSDocコメントを含める
};
// スキーマの生成
const generator = createGenerator(config);
const schema = generator.createSchema(config.type);
console.log(JSON.stringify(schema, null, 2));
3. オンラインツール：手軽に試せる選択肢
ちょっとした変換や、ツールの動作確認には、オンラインの変換ツールも便利です。
Transform.tools（https://transform.tools/typescript-to-json-schema）を使用すると、ブラウザ上で直接変換が可能です。以下のような特徴があります：
- 即座に結果が確認できる
- インストール不要で手軽に使える
- 小規模な変換に最適
ポイント
TypeScript型からJSONスキーマへの変換を効果的に行うために、以下のポイントに気をつけると良いでしょう：
-
型の制約を理解する
変換ツールでは扱えない複雑な型（例：条件付き型）があります。必要に応じて型定義をシンプルにすることをお勧めします。 -
生成されたスキーマの確認
自動生成されたスキーマは、必要に応じて調整が必要かもしれません。以下の点を確認しましょう：- 必須フィールドの設定
- 型の正確性
- 追加したいバリデーションルールの有無
-
パフォーマンスへの配慮
大規模なプロジェクトでは、型定義の変換に時間がかかることがあります。ビルドプロセスの一部として組み込むかどうかは、慎重に考慮したほうがよさそうです。
まとめ
TypeScript型からJSONスキーマへの変換は、選択肢の1つとして覚えておくと開発プロセスを効率化するテクニックになるかもしれません。ただ自動化するとデメリットもあることも判断材料として注意しておきたいですね。
- 小規模プロジェクト → typescript-json-schema
- 大規模/複雑なプロジェクト → ts-json-schema-generator
- 試験的な変換 → オンラインツール