入力 (JSON)

出力 (.proto スキーマ)

このツールでできること

実際の JSON ペイロード — API レスポンスのサンプル、Webhook のボディ、NoSQL ストアの 1 行 — を Protocol Buffers のメッセージとしてモデル化したいですか? スキーマを手で書くのは遅いし、特にネストされたオブジェクトや配列があると間違えやすい。このツールは JSON を歩き、各フィールドの Protobuf 型を推論して、プロジェクトにそのまま貼り付けられるきれいな proto3 スキーマを出力します。

型推論は自分で書くのと同じ流れです: 文字列は string、真偽値は bool、32 ビットに収まる整数は int32、それ以外は int64、整数でない数値は double、要素型が均一な配列は repeated <T> (オブジェクトの配列にはネストされたメッセージを 1 つ再利用)、ネストされたオブジェクトはネストされた message ブロック。JSON は struct と map を区別できないので、すべてのオブジェクトはネストされたメッセージとして出力されます — データが本当に map なら手で map<K, V> に書き換えてください。

フィールド名は camelCase や kebab-case から、Protobuf の慣例である snake_case に変換されます。フィールド番号は宣言順に 1, 2, 3, … と割り当てられます。出力は有効な proto3 です — .proto ファイルに貼って、protoc や buf を実行すれば、お好みの言語のコードが生成されます。変換はすべてブラウザ内で完結します — JSON もフィールド名も値も、どこにも送られません。

使い方

3 ステップ。整形された JSON オブジェクトなら何でも動きます — API レスポンス、ログエントリ、フィクスチャファイル、何でも。

JSON を貼り付ける

左のエディタに JSON を入れます。ルートはオブジェクト ({ ... }) でなければなりません — データが配列ルートなら、まずオブジェクトに包んでください。例: { "items": [...] }。現実的なデータを使ってください: サンプルが代表的であるほど、推論される型は長期的に欲しいものに近づきます。

JSON のキーがクォートされていなかったり、末尾カンマがあったり、その他の癖があるなら、まず JSON Fixer を通してください — Protobuf はクリーンなオブジェクトでないと動きません。

変換を押す

緑色の変換ボタンを押します。ツールは JSON のすべてのキーを歩き、Protobuf 型を選び、ネストされたオブジェクトのために message ブロックを構築し、先頭に syntax = "proto3"; を付けてスキーマを出力します。フィールド番号はソース順に割り当てられます。

.proto を使う

スキーマをリポジトリの .proto ファイルにコピーします。推論された型を確認してください — JSON サンプルが空 (空配列、null) だったフィールドには、型が推測であることを示すコメントが付きます。必要に応じて調整してから、protoc または buf generate を実行して、お好みの言語のコードを生成してください。

本当に時間が浮く場面

サードパーティ API を Protobuf でモデル化する

ベンダーが JSON を返す。あなたのサービスは Protobuf で保存する。実際のレスポンスを取って貼り付け、その型のスキーマのたたき台を得て、そこから磨きをかける。ドキュメントを読んで 50 個のフィールドを手で打つよりずっといい。

JSON ベースのサービスを gRPC へ移行する

HTTP+JSON のマイクロサービスを gRPC に移しているところです。リクエスト/レスポンスの形ごとに .proto が必要。キャプチャした各ペイロードを Protobuf スキーマに変換し、1 つのファイルにまとめて貼ると、契約のラフが出来上がっています。

Buf モジュールを立ち上げる

新しい Buf モジュールを立ち上げる際に、出発点となる現実的なスキーマが要りますか? 既存の JSON フィクスチャを変換して、その出力を .proto ファイルの種にしましょう — ゼロから打つよりずっと速い。

Protobuf コード用のテストフィクスチャを書く

チームには JSON のテストデータがある。新しいコードは Protobuf を消費する。JSON から <code>.proto</code> を生成し、codegen に型を作らせれば、フィクスチャとコードが揃ったままになります。

よくある質問

JSON はどこかに送られますか?

いいえ。変換はブラウザ内で JavaScript としてすべて実行されます。JSON — キー、値、機密情報を含むすべて — はあなたのマシンを離れません。DevTools を開いて、変換をクリックしながら Network タブを確認してください。リクエストは 0 件です。

int32 と int64 と double はどう選ばれますか?

整数値については、符号付き 32 ビット範囲 (-2^31 から 2^31-1) に収まるかをチェックします。収まれば int32、そうでなければ int64。整数でない数値は常に double になります。データが符号なしだと分かっている、または fixed32 のような特定の幅が欲しい場合は、出力を編集してください — 利用可能なすべての数値型とそのワイヤエンコーディング上のトレードオフはスカラー型表を参照してください。

オブジェクトはいつ map になり、いつネストされたメッセージになりますか?

常にネストされたメッセージ — map にはなりません。JSON は struct と map を区別しないので、どちらか推測すると半分くらいは外れます。データが実際にキー値マップ (メタデータ、ヘッダー、フィーチャーフラグなど) なら、出力を開いて message Foo { ... } を map<string, V> foo = N; に手で置き換えてください。データを見れば修正は機械的で明白です。

null と空配列はどうなりますか?

両方とも、出力に「縮退したサンプルから型を推測した」という旨のコメントが付きます。null は "nullable" 注記付きの string がデフォルト、空配列は "empty array" 注記付きの repeated string がデフォルトです。これらの型を、実際に期待するものに置き換えてください。

なぜ混合型の配列は repeated string になるのですか?

Protobuf は異種混合のリストを直接サポートしていません。JSON 配列が混合型 (一部は文字列、一部は数値) の場合、きれいな Protobuf 等価物はありません — google.protobuf.Value や oneof が必要、もしくはデータの形を見直すかになります。ツールはコメントで知らせるので、あなたが判断できます。

深くネストされた JSON も扱えますか?

はい。各ネストされたオブジェクトは、派生した PascalCase 名のネストされた message になります。ネスト深さはツールではなくスタック深さだけで制限されます — 非常に深くネストした API レスポンスでもきれいに変換されます。

この 2 つのツールで JSON ↔ Protobuf のラウンドトリップはできますか?

おおむね可能です。JSON から Protobuf でスキーマが、Protobuf から JSON でサンプルが得られます。JSON サンプルに代表的な値があったフィールドは形が一致します。JSON が null や空配列だった箇所は、推論された Protobuf 型は推測なので、型を直してからでないとラウンドトリップは厳密には合いません。

JSON から Protobuf 変換ツール