What Is a Protobuf Schema? Protocol Buffers Explained

A protobuf schema is a .proto file that defines the structure of messages for Protocol Buffers, a compact binary serialization format from Google.

Protocol Buffers (protobuf) is a fast, compact, schema-driven way to serialize data, used heavily for service-to-service communication. The schema - a .proto file - is the contract: it declares the fields of each message, and a compiler turns it into code in your language. Building protobuf into a project means a code-generation step that belongs in CI.

What a protobuf schema is

A protobuf schema is a plain-text .proto file that declares messages and their fields, each field having a type, a name, and a unique number. The numbers, not the names, identify fields on the wire, which is what lets protobuf encode data compactly and evolve safely.

Schema-driven binary encoding

Unlike JSON, protobuf does not embed field names in the serialized bytes - it uses the field numbers from the schema. That makes the output small and fast to parse, but it also means you cannot read the bytes without the schema. The schema is mandatory, not optional documentation.

Code generation

A compiler reads the .proto file and generates classes or structs in your target language for encoding and decoding messages. This generated code is what your application actually imports. Because it is generated, it is usually regenerated in CI rather than committed, keeping it in sync with the schema.

Protobuf in CI

CI builds typically run the protobuf compiler to regenerate code, lint the schema for style and breaking changes, and verify backward compatibility so a schema edit cannot silently break existing clients. Breaking-change detection on the .proto file is a valuable CI gate for shared APIs.

Protobuf checks in a pipeline

# Generate code and check compatibility in CI
steps:
  - run: buf lint
  - run: buf breaking --against ".git#branch=main"
  - run: buf generate

Latchkey note

The protobuf compiler and tools like buf are just CLIs your job installs. On Latchkey those tool downloads are cached between runs, so code-generation jobs do not re-fetch the compiler every build.

Key takeaways

A protobuf schema is a .proto file declaring messages and numbered fields for a compact binary format.
Encoding uses field numbers, not names, so the schema is required to read the bytes.
CI regenerates code from the schema and gates breaking changes to protect existing clients.