入力(.proto スキーマ)

出力(バリデーションレポート)

このツールができること

Protocol Buffers ファイルを保存して protocbuf を走らせたら、ビルドが意味不明な行番号エラーで落ちる──そういう経験はありませんか。このバリデーターは厳格なコンパイラと同じルールで .proto をパースし、何が間違っているかをわかりやすい言葉で教えてくれます。コミットして CI に拾われる前に、手元で潰せます。

「パースできたかどうか」だけでなく、spec が実際に要求するチェックも lint パスとして実行します。フィールド番号は 1..536870911 の範囲内であること、19000..19999Google が内部用に予約しているレンジであること、メッセージ内のフィールド番号は重複してはならないこと、フィールド名も重複してはならないこと。これらは実際のビルド失敗を引き起こす違反で、コンパイラが 1 件ずつ吐くのに対し、バリデーターは一度にすべて表示します。

すべてはブラウザ内で動きます。.proto、メッセージ名、パッケージパスがマシンの外に出ることはありません。パーサーは syntax/package/import ディレクティブ、行コメント・ブロックコメント、ネストされた messageenum ブロック、oneofmap<K, V>repeatedoptional、サービス(スキップ)、フィールドオプションを処理します。公式の proto3 言語ガイドと同じワークフロー向けに設計されています。

使い方

3 ステップ、入力中に走ります。出力エディターは入力停止から約 300 ms 後に更新されます。

1

.proto スキーマを貼り付け

スキーマを左側のエディターに投入してください。1 ファイル、長さは問いません。先頭の syntax = "proto3"; はあっても省略しても OK です。import 文は認識されますがスキップされます(ファイルをまたいだ解決はここのスコープ外です。インポートされたメッセージも検証したい場合はインライン展開して貼ってください)。コメントはパース前にすべて取り除かれます。

貼り付けで「スマートクオート」が混じると、バリデーターがトークン化エラーを出すことがあります。除去するか、プレーンテキストのソースから貼り直してください。

2

レポートを読む

右側に、スキーマがクリーンなら緑のチェック、そうでなければ問題のリストが出ます。各問題はメッセージとフィールドをピンポイントで示すので、grep せずにエディターで直せます。レポートにはメッセージ数、enum 数、総フィールド数のサマリも含まれます。

3

直して貼り直す

エディターで修正を当て、更新後のスキーマを貼り付けると、出力は 1 秒以内に再検証されます。リロードもリビルドも不要、CI が赤で戻るのを待つ必要もありません。スキーマがクリーンになったら、検証の記録として PR コメントにレポートをコピーするのも手です。

実際に時間が浮く場面

CI に push する前にエラーを捕まえる

チームが CI で buf lint を回している場合、ローカルで先に検証しておけば「push して待って赤を見て直してまた push」のサイクルが、ブラウザのタブ 1 枚に圧縮されます。

同僚の Protobuf PR をレビューする

同僚のスキーマ変更をレビューしたいけれど、ローカルに protoc のツールチェーンを入れていない。新しい .proto をここに貼って構造的にクリーンか確かめれば、「よさそう、マージ」ではなく的を絞ったレビューが残せます。

proto2 から proto3 への移行

古いスキーマには required(proto3 では消えた)が残っていたり、ぱっと見は問題なくても確認するとアウトなフィールド番号が混じっていたりします。バリデーターは重複と範囲外を一度に指摘してくれるので、800 行の .proto を目視で読むより圧倒的に速いです。

コード生成ツールが吐いた .proto を検証する

ジェネレーター(例:JSON Schema → Protobuf、OpenAPI → Protobuf)はときどきエッジケースのある出力を吐きます──重複フィールド番号、予約レンジ抵触など。信用する前にバリデーターを通しましょう。

よくある質問

.proto スキーマはサーバーに送信されますか?

いいえ。パーサーと lint チェックは、ブラウザ内で JavaScript として完結しています。DevTools を開いて Network タブを見ながら貼り付けてみてください──リクエストはゼロです。社内型名やパッケージパスなど、サードパーティのバリデーターには出したくない情報を含むスキーマでも安心です。

lint パスは具体的に何をチェックしますか?

フィールド番号は 1..536870911 の範囲(Google 予約の 19000..19999 を除く)、メッセージ内のフィールド番号は一意、メッセージ内のフィールド名も一意であること。違反はすべて message.field という正確なパス付きで報告されます。パース段階でも、セミコロン抜け、波括弧の不一致、想定外のトークンなどで失敗します。

検証は proto3 spec に対してですか、それとも proto2 ですか?

両方の構文を受け付けます(proto3 のデフォルト 0、proto2 の required/optional 修飾子など)。lint チェックは spec で定められたもので、両方に適用されます。「proto3 で required は不可」のような最も厳しいチェックはここでは強制しません──protoc 本体が拾います。

なぜフィールド番号 19000 が指摘されるのですか?

19000..19999 のレンジは、Google が Protocol Buffers の実装用に内部的に予約しています。このレンジのフィールド番号を割り当てると、本物の protoc はスキーマを拒否します。バリデーターはこれを早期に拾うので、混乱した build エラーから知るのではなくこのツールから知ることができます。

import を辿りますか?

いいえ。import 文は認識されますがスキップされ、別ファイルのメッセージ型は「不明」として解決され検証されません。インポート型に依存するメッセージを検証したい場合は、インポートされたメッセージを同じ入力に貼り付けてください。

どのくらいの大きさのスキーマまで扱えますか?

数万行でも余裕です。検証はローカル、アップロードなし、レート制限なし、ネットワーク往復なし──リポジトリ丸ごと貼っても構いません。上限はブラウザのメモリです。

関連ツール

Protobuf と JSON を扱うなら、これらと組み合わせるのがおすすめです: