日本語English

GraphQL スキーマ確認・破壊的変更チェック

GraphQL の SDL（schema.graphql）を貼るだけで、型・フィールド・引数の一覧と、未定義の型などの指摘を行番号つきで出します。旧と新の 2 つを比べると、フィールドの削除や引数の必須化など、破壊的変更の候補を安全な変更と分けて示します。定義はブラウザの外へ送りません。

端末内で処理・アップロードなしスマホ対応オフライン対応

ファイルや入力内容はお使いの端末（ブラウザ）の中だけで処理され、サーバーへは送信されません。

変更前（古い定義）
0 / 300,000
変更後（新しい定義）
0 / 300,000
1 つの SDL は 30 万文字まで。Ctrl（⌘）+ Enter で差分を調べます。
SDL を貼り付けて「スキーマを確認」か「差分を調べる」を押すと、ここに結果が出ます。
判定の規則
  • 破壊的変更の候補 クライアントが今までどおり動かなくなるおそれがある変更です（候補）。
  • 安全な変更 既存のクライアントはそのまま動く変更です。

使い方

  1. 「変更前（古い定義）」に古い SDL、「変更後（新しい定義）」に新しい SDL を貼るか、「ファイルを開く」で schema.graphql を読み込みます。「サンプルで試す」でも確かめられます。

  2. 1 つだけ確かめたいときは「スキーマを確認」を押します（左の欄を読みます）。2 つを比べるときは「差分を調べる」を押します（Ctrl または ⌘ + Enter も使えます）。

  3. 確認では、型の一覧・入口から辿れる型の木・行番号つきの指摘が出ます。差分では、破壊的変更の候補と安全な変更の件数と一覧が出ます。

  4. 「Markdown をコピー」で PR の説明に貼れる表にできます。「JSON を保存」では、判定・件数・変更の一覧を保存します。

できること

型の一覧と入口からの木

type・interface・union・enum・input・scalar・schema・extend を読み、Query・Mutation・Subscription から辿れる型を木で示します。

行番号つきの指摘

未定義の型、名前の重複、interface のフィールドの実装漏れ、空の enum、input に出力用の型を使った箇所などを、行番号つきで出します。

破壊的変更の候補を分ける

フィールド・型の削除、引数の必須化、nullable から non-null への変更、enum 値の削除などを候補として示し、追加などの安全な変更と分けます。

判定の理由を各行に

どの規則でその区分にしたかを行ごとに書きます。規則の一覧も画面で読めるので、レビューの根拠にできます。

ブラウザの中だけで処理

SDL は送信せず、ブラウザの中だけで解析します。URL からスキーマを取りに行くことはしません。

こんなときに

  • GraphQL の schema.graphql を PR に出す前に、既存のクライアントを壊す変更がないかを確かめたい
  • 未定義の型や名前の重複を、コードを動かす前に行番号つきで見つけたい
  • 入口（Query・Mutation）から辿れる型を一覧して、スキーマの全体像をつかみたい
  • 社内の GraphQL スキーマを外部に送らずに、旧新の差を調べたい

対応形式

入力

SDL（schema.graphql の形）.graphql / .gql / .txtUTF-8（BOM 付き可）

出力

画面の一覧（型・指摘・差分）Markdown（PR 用の表）JSON（判定・件数・変更の一覧）

対応状況

機能対応補足
SDL の読み込み（type・interface・union・enum・input・scalar・schema・extend）対応—
フィールド・引数・型（! と [ ]）・description（"..." と """..."""）・@deprecated対応—
入口（Query・Mutation・Subscription）から辿れる型の木対応—
指摘: 未定義の型・名前の重複・interface の実装漏れ・空の enum・input に出力型対応仕様の全項目を検証するわけではありません。読んだ範囲の指摘です
旧新の比較と、破壊的変更の候補・安全な変更の区分対応候補です。API ごとの方針や利用状況は分からないため、一般的な規則で示します
解析できない構文一部対応読めない行は行番号で示し、その定義は読み飛ばします。読めた部分だけで判定します
ディレクティブの定義の差分非対応比べません
introspection の結果（JSON）から SDL への変換非対応対応していません。SDL を貼ってください
クエリの実行・検証、サーバーへの接続非対応通信しません
別ファイル・URL からの import や取得非対応取得せず、読めない参照として扱います
判定の規則を変える設定非対応規則は画面で読めますが、区分を変える設定はありません
オフラインでの利用対応一度開いたあとは通信なしで動作します

制限・注意事項

  • 1 つの SDL は 30 万文字まで。ファイルは 1 MB まで読み込みます。
  • 型の木は深さ 12 段・2,000 件まで。超えた部分は省略して示します。
  • 指摘と変更の一覧は、件数を全件数えたうえで画面に出します。
  • 判定は一般的な規則によるもので、API ごとの方針によって変わります。

プライバシーと安全性

SDL はお使いのブラウザの中だけで解析し、送信も保存もしません。ページを閉じると内容は消えます。analytics には、入力の中身や件数を含まない実行の記録だけを送ります。

よくある質問

GraphQL の破壊的変更とは何ですか？
クライアントが今までどおり動かなくなる変更のことです。フィールドや型の削除、引数の必須化（nullable から non-null）、出力フィールドの non-null から nullable への変更などが該当します。このツールは GraphQL 仕様の考え方で候補を示します。
introspection の結果（JSON）は貼れますか？
今のところ貼れません。このツールは SDL（schema.graphql の形）を読みます。introspection の JSON を SDL に変換することも、サーバーへ接続することもしません。
スキーマの定義が正しいかを完全に検証できますか？
いいえ。未定義の型、名前の重複、interface の実装漏れなどを見る軽い検査です。仕様のすべての検証は行わないので、最終確認は GraphQL のツールも併用してください。
REST の OpenAPI の差分とどう使い分けますか？
REST の API の定義は「OpenAPI 差分・破壊的変更チェック」、GraphQL のスキーマは、このツールを使います。OpenAPI は HTTP の API の定義、GraphQL は型の定義を比べる点が違います。
SDL はどこから書き出せばよいですか？
サーバーのライブラリが出力する SDL、またはリポジトリの schema.graphql をそのまま貼ってください。読み込みは「ファイルを開く」でもできます。

OpenAPI ビューア・検証（OpenAPI Studio）

OpenAPI 3.0 / 3.1・Swagger 2.0 の定義を貼り付けるだけで、タグ別のエンドポイント一覧とスキーマのツリーを表示し、公式スキーマと照らして誤りを行・列つきで示します。API の呼び出しや外部ファイルの取得はせず、定義は端末の外へ送信しません。

アップロードなし

JSON→型・Schema生成（Schema Codegen）

JSON のサンプル・JSON Schema・OpenAPI を貼ると、10 種類の形式の型定義を生成します。複数のサンプルを並べると、省略されるキーや型の違いも推論します。データは端末の外へ送信しません。

アップロードなし

JSON 整形・検証（JSON Studio）

JSON を貼り付けるだけで整形・1 行化・構文チェック。エラーは「何行目の何が悪いか」まで表示し、コメントや末尾カンマは自動修復できます。データは端末の外へ送信しません。

アップロードなし

AsyncAPI 確認・イベント API 差分チェック

AsyncAPI の YAML・JSON を貼るだけで、サーバー・チャンネル・操作・メッセージの一覧と、解決できない $ref や使われていない components の指摘を行番号つきで出します。旧と新を比べると、チャンネルや操作の削除、payload の項目の削除や必須化などの候補を示します。定義はブラウザの外へ送りません。

アップロードなし

proto ファイル確認・protobuf 互換性チェック

.proto の内容を貼るだけで、メッセージ・フィールドの番号・型・ラベル・enum・rpc の一覧と、番号の重複や範囲外などの指摘を行番号つきで出します。旧と新の 2 つを比べると、フィールド番号の変更や型の変更など、互換性を壊すおそれのある変更を、注意や安全な変更と分けて示します。定義はブラウザの外へ送りません。

アップロードなし

テキスト・コード Diff

変更前と変更後を貼り付けるかファイルをドロップするだけで、追加・削除された行と、行の中で変わった単語まで色分けして表示します。結果は unified 形式のパッチとしてコピー・保存でき、入力はブラウザの外へ出ません。

アップロードなし

最終更新: