What is the Protobuf Reader?

Reading somebody else's Protocol Buffers schema is one of those tasks that always takes longer than you expect. The keywords are terse, the field numbers look magic, and a single oneof can change the meaning of three other fields. The Protobuf Reader takes the schema apart for you and lays out every message and enum as a small, focused table so you can read it the way you'd read documentation, not source code.

Each row tells you what a field is called, what type it carries, what its tag number is, and whether it's repeated, optional, or part of a map. Enums show their values and their integer codes side by side. The point is to make a .proto file you've never seen before legible in a few minutes — you don't have to know wire format or have protoc installed to follow along.

The schema you paste stays in your browser. Nothing is sent anywhere. Close the tab and there's no history of what you read.

How to Read a .proto Schema Here

Three small steps that map to how you actually read code you didn't write — start broad, narrow in, then check the parts that matter.

Drop the Schema In

Open the .proto file (from a repo, a code review, a vendor SDK), copy the contents, and paste them on the left. Or hit Sample to load a small e-commerce schema and try the reader against something familiar before you point it at a real file.

message Customer {
  string id = 1;
  string name = 2;
  Address shipping_address = 4;
  optional string promo_code = 7;
}

Notice the gap between field 2 and field 4 in the example — protobuf field numbers don't have to be sequential, and gaps usually mean a field was deleted. The reader shows you the numbers so those gaps are visible.

Read the Top-Level Shape First

Each top-level message shows up as a row, with its fields shown in a nested table. Read the message names first to get a feel for the domain — Order, Customer, Payment tells you a lot before you look at any field. Enums get their own rows; reading the enum names alongside the messages is usually the quickest way to map the data model in your head.

Look at Field Rules and Types

For each field the reader shows the rule column: singular (one value), repeated (a list), optional (proto3-style optional), or map (a key-value map). The type column shows the actual type, including for maps where you see map<string, string>. These two columns answer most questions you'll have about how a field is meant to be used. The semantics follow the proto3 language guide.

Use Filters to Trace a Concept

When you're trying to find every field that references a particular message, type its name in the type column's filter box — every row that mentions Customer shows up. Same trick for finding all the maps (map in the rule column), all the lists (repeated), or every field with a number above 100 (often added later in a schema's life).

Switch Layouts for Wide Schemas

Hit Full Screen when a schema has more than a dozen messages — you get the table at full viewport width and stop fighting the editor pane. Use Main or Nested to flip a table's orientation; sometimes reading fields as rows and messages as columns is easier when one message has way more fields than the others. Field numbering rules are explained in the field number assignment guide if a number jumps out at you.

When the Reader Helps

Inheriting a Codebase

You've joined a team that uses protobuf for everything and you've been handed a 40-file proto/ directory. Open the main service's .proto here, read through the messages once top-to-bottom, and you have the data model in your head before your first stand-up. Way faster than reading 40 files of generated Java to back into the schema.

Code Reviewing a Schema Change

Somebody opens a PR adding three new fields and renaming a fourth. Drop the post-change .proto in the reader to see the result laid out, then drop the pre-change version to compare. You spot in seconds whether the renamed field reused its number (good — wire-compatible) or got a new one (bad — breaks old clients reading the field).

Reading a Vendor's API Schema

A payment provider ships their API as a .proto. You don't need to generate code yet — you need to understand whether RefundRequest takes a customer ID or a transaction ID, and whether amount is in cents or a fixed-point decimal. Paste the file, find the message, read the fields. Saves you a trip to the vendor's docs.

Learning Protobuf for the First Time

Just starting with protobuf? Reading example schemas from the grpc repo through the reader instead of in a text editor is a gentler ramp — the rule and type columns make the field-number-and-rule pattern click much faster than reading the raw syntax cold.

FAQ

How is the Reader different from the Protobuf Viewer?

They share a UI but the framing is different. The Viewer is for when you wrote the schema (or already know it) and you just want to scan it quickly. The Reader is for when you didn't write it — the copy and the layout are tuned for comprehension, not just browsing. Same parser under the hood; pick the framing that matches what you're trying to do.

What does the "rule" column actually mean?

In proto3, every field is either singular (one value, the default), repeated (zero-or-more values, like an array), optional (one value but tracks whether it was set explicitly), or part of a map. The reader normalizes required from proto2 to singular because proto3 dropped the concept. If a field shows repeated on the wire it's always a list, never a single value.

Why do I see gaps in the field numbers?

Field numbers are stable identifiers in protobuf — once a number is assigned, it stays. When somebody removes a field, the number is usually never reused (often there's a reserved 5; declaration to enforce that). So gaps in the numbering tell you the schema has had fields removed over time. That's normal and intentional, not a bug.

Do I need to know the wire format to read a schema?

Not for reading. The reader shows you the field name, type, and number — that's enough to understand what data the schema describes. The wire format matters when you're writing a parser by hand or debugging cross-version compatibility, not when you're trying to understand what a message represents.

What about map fields and oneofs — do they show up?

Yes. Map fields show as map<K, V> in the type column with map in the rule column. Oneofs are flattened into the message's field list (the parser doesn't draw the oneof grouping in the table — that's by design, the focus is field shape, not declaration syntax). If you need the oneof grouping visible, the raw schema in the editor pane on the left has it.

Is the schema text uploaded or stored anywhere?

No. Parsing runs entirely in your browser via JavaScript. The .proto text doesn't leave the page. If you're reading something proprietary or under NDA, that's the right answer — paste it, read it, close the tab and nothing persists.

Related Protobuf Tools

Reading is one task — if you need to do something else with the .proto, try one of these: