01
ルートは最初のmessageから選ばれる
enumやserviceではなく、ソース内で最初に宣言されたmessageが初期ルートです。設定欄で完全修飾名を選ぶと変更できます。ソースを編集すると選択はリセットされるため、削除した型が古い選択のまま残りません。
Protocol Buffersの定義
Protobuf整形
importを必要としないproto3定義を入力し、構造、整形済みソース、JSONの形を切り替えて確認できます。
Protobuf整形
Proto3ソース
結果
ソースはブラウザ内で処理します。import先の取得やネットワーク送信は行いません。
設定
単一ファイルのproto3サブセットに対応。import、独自オプション、コンパイル、互換性チェックは対象外です。ソースの編集でルート選択がリセットされます。
上限：UTF-16で100,000文字、20,000トークン、2,000宣言、32階層。タイムアウトは8秒です。
結果が古いため、コピーとダウンロードを無効にしています。
Protobuf整形が必要になるのは、短く詰められた定義をレビューしたいときだけではありません。読みやすいソースにも、重複したフィールド番号や解決できない型参照は残り得ます。このワークベンチは対応範囲の宣言を確認してから結果を生成します。
ツリーにはソース上の名前、wire上の番号、解決先の型を表示します。JSON Schemaが示すのは選択したメッセージのデータ形状です。サービス定義や過去に使った番号など、投影に含まれない情報を確認するため、元の契約も残してください。
Protobuf整形をレビューに使う理由
同名の型を取り違えない
Protobuf整形では宣言順を維持し、ネストされた型の参照先を完全修飾名で表示します。OuterA.ItemとOuterB.Itemは別の定義です。自己参照はパスとして示すため、循環するメッセージでもツリーが無限に展開されることはありません。
利用するメッセージだけをルートにする
一つのファイルに複数のmessageがある場合も、JSON Schemaのルートを指定できます。各定義を$defsにまとめ、参照は$refで表現します。繰り返し、map、oneofを見比べながら、利用側が期待する形を確認できます。
操作前に知っておきたい三つのこと
02
折りたたみは閲覧だけの操作
ツリーの宣言は折りたたみ可能で、行番号からソース位置へ戻れます。長い結果は可視項目を50件ずつ表示します。構造データのコピーには折りたたんだ項目や未表示の項目も含まれ、表示のために内容が失われることはありません。
03
手動実行と取り消しを使い分ける
入力後350ミリ秒で自動チェックが走ります。オフにすると実行ボタンとCtrl/Cmd + Enterが使えます。変更直後は古い結果をエクスポートできません。サンプルとクリアは置換文字数を確認してから適用し、一度だけソースと結果を同時に戻せます。
排版と意味の確認を分けて読む
コメントを残すprotoファイル整形
インデントは2または4スペース。文字列内の波括弧やセミコロンを構造として処理せず、コメントの内容も保ちます。名前、番号、フィールド順は変更しません。整形結果を別欄に出し、再解析した記述子が元と一致することを確認してからエクスポートを許可します。
構文検証とフィールド番号の重複チェック
メッセージ内のタグは正の整数で、一意かつ19000–19999の範囲外である必要があります。後から書かれたreservedも検査対象です。enumでは最初の値がゼロか、数値エイリアスにallow_aliasがあるか、予約と競合していないかを別に調べます。
前方参照と再帰を含む構造表示
package、message、enum、oneof、service、RPCをツリーで確認できます。型の検索範囲は同じファイル内です。参照先がなければ出力を停止し、任意のオブジェクトで代用しません。JSON側がlowerCamelCaseでも、ツリーのフィールドは元のsnake_caseを保持します。
ルート付きの2020-12スキーマ
repeatedは配列、mapはオブジェクト、int64は文字列に対応させます。完全修飾名を$defsに使うため、同名のネスト型を上書きしません。oneofはゼロまたは一つのメンバーを許可します。普通のフィールドもoptionalも省略可能で、勝手にrequiredを追加しません。
対応範囲と出力の限界
- 明示的なproto3だけを受け付ける
- 先頭にsyntax = "proto3";が必要です。proto2、Editions、required、group、extensionsには対応しません。TimestampやAnyなどの既知の型も含め、importはすべて拒否します。依存関係を含む定義は、完全なファイル構成を持つプロジェクト側で確認してください。
- オプションは対応一覧に限定
- 一般的なファイル単位のコード生成設定と、正しい位置のjson_name、packed、deprecated、allow_aliasを扱います。独自オプション、集約オプション、検証注釈、CELは対象外です。コード生成設定はソースに残りますが、JSON Schemaの業務制約には変換されません。
- ProtoJSONの全入力形式は表さない
- 投影は一般的な出力形状を対象にします。nullによる未設定、整数のenum、寛容な数値文字列入力を完全には再現しません。64ビット整数文字列のパターンは値域検証ではなく、base64のcontentEncodingも注釈です。実データに使う前に必要な制約を補ってください。
- 契約の修正や互換性判定はしない
- フィールドを振り直したり、reservedを削除したり、整形したソースを入力へ上書きしたりしません。過去の版で使われた番号は現在の一枚から分かりません。protocのコンパイル、Buf lint、破壊的変更の検出、クライアント生成、OpenAPI出力は対象外です。
- 大きすぎる入力はエラーで停止
- 上限はUTF-16で100,000文字、20,000トークン、2,000宣言、32階層です。結果は1,000,000文字までで、ワーカーの実行時間は8秒です。上限を超えた場合にソースを切り詰め、部分的な結果を成功と表示することはありません。
- 入力はメッセージデータではない
- 対象は.protoの宣言です。バイナリ、Base64、TextFormatのペイロードをデコードするツールではありません。JSON Schemaからの逆変換、複数ファイルの一括処理、外部URL取得、ソース入りの共有リンクは用意していません。
Protobuf整形のよくある質問
フィールド番号をゼロから始められますか？
メッセージのタグは1から536870911までで、19000から19999は実装用に予約されています。一方、proto3のenumは最初の宣言値がゼロでなければなりません。似た数字でも役割が違うため、このツールはフィールド番号と列挙値を別々の規則で確認します。
フィールド番号を飛ばしてもよいですか？
連番である必要はありません。たとえば1の次が20でも、重複や予約との競合がなければ有効です。整形では空きを詰めず、宣言順も保ちます。削除した番号を再利用させたくない場合はreservedを使います。単なる欠番だけでは過去の利用履歴は記録されません。
proto3でoptionalフィールドを宣言するには？
型の前にoptionalを付けると、生成コードで明示的な存在性を扱えます。ツリーにもその宣言を表示します。ただしJSON Schemaでは通常の単一フィールドもoptionalも省略可能です。生成されるhasメソッドや、未設定と既定値の違いまで表現するものではありません。
int64がJSONでは文字列になるのはなぜですか？
JavaScriptの通常の数値では64ビット整数の全域を正確に保持できません。一般的なProtoJSON出力は十進文字列を使うため、投影でも文字列にします。Numberへ変換して精度を落とす処理はありません。ただしパターンが確認するのは書式であり、符号付き・符号なしの正確な値域には追加検証が必要です。
正しいパスのimportでも失敗するのはなぜですか？
コンパイラーは設定された検索ルートから依存ファイルを探します。この画面にはファイルツリーや依存解決の環境がないため、パスの正しさにかかわらずimportを拒否します。依存ファイルをそろえたprotocやBufを利用してください。パスを取得したり、宣言を無視して成功にしたりはしません。
対応すべき定義で問題がありましたか？
次の定義をレビューする
Protobuf整形で対応範囲の構造を確認し、ソースと見直したJSONの形をプロジェクトへ戻してください。最終コンパイルには完全な依存関係が必要です。