01
公開済みSDLを旧版に置く
古いスキーマから新しいスキーマへの変更を判定します。左右を交換すると同じ二つの文書でも削除と追加が逆になり、リスク分類も再計算されます。
GraphQL文書
GraphQLスキーマ差分公開前に契約の変化を確認
公開中の完全なSDLを左、新しい完全なSDLを右に入力してください。比較の向きで削除と追加の意味が変わります。
GraphQLスキーマ差分
旧スキーマのSDL
新スキーマのSDL
差分
完全なスキーマSDLを2つ入力するか、サンプルを読み込んでください。
2つのSDLはこのブラウザー内だけで解析します。APIへの送信、アップロード、履歴保存、URLへの入力追加は行いません。
オプション
破壊的変更と潜在的な危険はGraphQL.jsが判定します。それ以外の構造変更と非推奨の変更は別に表示し、安全とは断定しません。
SDLは各100,000文字、20,000トークン、ネスト100段まで。比較は8秒で停止します。
完全なスキーマSDLを2つ入力するか、サンプルを読み込んでください。
GraphQLスキーマ差分は、プルリクエストでSDLの並びや空白が大きく変わったときに役立ちます。文字の違いではなく、既存のクエリが依存する型、フィールド、引数の契約を追えます。 GraphQLスキーマ比較でも、基準は文字列ではなく型の意味です。
構造変更と互換性の判定は同じものではありません。GraphQL.jsが破壊的変更として挙げなかった新規フィールドや非推奨の印も記録し、レビューで見落とさないようにします。
GraphQLスキーマ差分を使う理由
SDLの見た目ではなく、API契約の変化を見るための比較です。
定義順の変更に惑わされない
GraphQLスキーマ差分はSDLを解析してから型・フィールド・引数のパスを比較します。並び替えやインデントは差分にならず、削除されたフィールドはその名前と旧値が明示されます。
危険度と非推奨を混同しない
enum値の追加は潜在的な危険として扱われます。一方、@deprecatedを付けても既存のフィールドはまだ使えます。GraphQLスキーマ差分はこの印と新しいフィールドを別々に残し、未判定を安全と言い換えません。
比較の向きと結果の鮮度を確かめる
02
自動実行を必要に応じて切り替える
標準では入力が約350ミリ秒止まると比較します。長いSDLを貼り付ける間は自動を切り、比較ボタンまたはCtrl/Cmd+Enterで現在の二つだけを処理できます。
03
エラーを直してから書き出す
入力を編集すると前回の結果は古くなり、コピーと保存は使えません。旧版・新版のどちらで失敗したかと行列を確認して再実行してください。表示は100件ずつでも、保存するレポートには全件が入ります。
構造、規則、非推奨を一つの報告に
SDLの意味に沿ったパス
型、フィールド、引数、入力型、enum、union、ディレクティブを比較します。空白や定義順の差はAPIの変更として数えません。
GraphQL.jsの互換性規則
破壊的変更と潜在的な危険にはGraphQL.jsの規則を用い、その識別コードも表示します。その他の構造変更は「安全」と断定せず残します。 互換性チェックの根拠を辿れます。GraphQL Inspectorのような外部CI設定は不要です。
非推奨と全件の出力
@deprecatedの追加や理由の変更を独立して表示します。非推奨になったフィールドを後で削除すれば破壊的変更のままです。
静的なSDL比較で分からないこと
- 完全で有効なSDLが必要
- Queryルートを欠く断片や未定義型の参照は完全なスキーマになりません。GraphQLスキーマ差分はその場合に比較結果を出さず、入力側と可能なら行列を示します。
- 実際のクライアント利用は調べない
- 破壊的という分類は既存の操作が失敗し得ることを示します。利用中のクエリやトラフィックは読み取らないため、特定の利用者への影響は別途確認してください。
- URLと内省JSONを直接読まない
- このページは二つのSDLテキストだけを扱います。GraphQLエンドポイントに接続したりQueryを実行したりせず、内省JSONはあらかじめSDLへ変換する必要があります。
- 名前の変更は推測しない
- 型やフィールドの改名は旧名の削除と新名の追加です。@deprecatedが付いていた旧名でも削除は自動的に免除されません。
GraphQLスキーマ差分のよくある疑問
Mutationの引数をnull許容にすると破壊的変更になりますか？
Mutationの必須引数をnull許容にすると受け付ける入力が広がるため、GraphQL.jsは通常その方向を破壊的変更としません。逆に必須へ狭めると古い呼び出しが失敗し得ます。
GraphQLのenumに値を追加すると破壊的変更になりますか？
enum値の追加はクエリ検証を直ちに壊さなくても、全値を列挙しているクライアントには想定外です。そのため潜在的な危険として扱います。
GraphQLの型を互換性を保ったまま改名できますか？
二つのSDLから改名の意図は分かりません。GraphQLスキーマ差分は旧型の削除と新型の追加を別々に示します。移行期間を設けるかどうかはAPI側で決めてください。
GraphQLのMutationを非推奨にできますか？
Mutationはルート型のフィールドなので@deprecatedを付けられます。印を付けても古い操作は残り、後日の実際の削除は標準規則では破壊的変更です。
非nullのフィールドをnull許容にすると破壊的変更になりますか？
戻り値を非nullからnull許容にするとクライアントの型の前提が変わるため、GraphQL.jsは破壊的と判定します。逆方向でもresolverが本当にnullを返さないかは別途試験が必要です。
期待と違う結果になりましたか？