Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 39 ยท Protobuf Language

Protobuf Packages, Imports, Nested Types and Options

Organize .proto files with packages, imports, nested messages and file options such as go_package and java_package. Runnable Go stand-ins resolve names and order imports.

A single .proto file is fine for a demo. A real system has dozens of them: shared types such as Money and Address, one file per service, and versions that evolve. This lesson shows how to organize contracts with packages, imports, nested types and options, and how to lay them out on disk so that tools such as protoc and buf can find everything.

.proto snippets are read-only (the compiler cannot run here). Two Go stand-ins model how the compiler resolves names and orders imports.

Packages

PROTO
syntax = "proto3";

package shop.v1;

A package is a namespace. The full name of a message is shop.v1.Product. Two files can both define Product as long as their packages differ. Conventions:

  • Use a dotted lowercase name: company.product.v1.
  • Put a version in the package (v1, v2). When you need a breaking change, create v2 side by side instead of editing v1. See the versioning chapter on the track page.
  • The package also becomes part of every method path: /shop.v1.Catalog/GetProduct.

Imports

Use import to use types from another file:

PROTO
import "shop/v1/money.proto";
import "google/protobuf/timestamp.proto";

message Product {
  int64 id = 1;
  shop.v1.Money price = 2;
  google.protobuf.Timestamp created_at = 3;
}

Import paths are relative to a root given with --proto_path (or -I), not to the importing file. With the layout

Text
proto/
  shop/v1/product.proto
  shop/v1/money.proto

you run protoc --proto_path=proto ... and import "shop/v1/money.proto". Matching the directory structure to the package name (shop/v1 for shop.v1) is the standard style.

Variants:

  • import public "other.proto"; re-exports everything in other.proto to files that import this one. It is useful when moving a type to a new file without breaking importers.
  • import weak is deprecated; do not use it.
  • Circular imports are forbidden. If a.proto imports b.proto, then b.proto cannot import a.proto, directly or indirectly. Extract shared types into a third file.

Name resolution

Inside package shop.v1, a reference such as Money is looked up from the innermost scope outward: first nested scopes, then shop.v1, then shop, then the root. A leading dot (.shop.v1.Money) forces a fully qualified lookup.

Stand-in 1: resolving a type name like protoc

Go Stand-in: scope lookup of type names

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Nested messages and enums

Types used only by one message can live inside it:

PROTO
message Product {
  message Dimensions {
    double width_cm = 1;
    double height_cm = 2;
  }
  enum Size {
    SIZE_UNSPECIFIED = 0;
    SIZE_SMALL = 1;
    SIZE_LARGE = 2;
  }

  int64 id = 1;
  Dimensions dimensions = 2;
  Size size = 3;
}

From outside, the full name is shop.v1.Product.Dimensions. In Go it becomes Product_Dimensions; in Java, Product.Dimensions. Nesting is good for tightly coupled types, but if several messages need the type, define it at top level. Deeply nested types make generated names awkward and cannot be reused.

File options

Options are hints for generators. They do not change the wire format.

PROTO
option go_package = "example.com/shop/gen/shop/v1;shopv1";
option java_package = "com.example.shop.v1";
option java_multiple_files = true;
option csharp_namespace = "Example.Shop.V1";
option optimize_for = SPEED;
  • go_package is mandatory for Go generation: an import path, optionally followed by ; and the Go package name.
  • java_multiple_files = true generates one Java file per message instead of nesting everything in one outer class.
  • Field options include deprecated = true and json_name = "...":
PROTO
message Product {
  string old_code = 5 [deprecated = true];
  string display_name = 2 [json_name = "title"];
}

deprecated makes generated code carry a deprecation warning, which is the polite way to retire a field before removing it. The json_name option matters only for the JSON mapping used by gateways and the JSON form of protobuf.

The JSON mapping

Protobuf defines a canonical JSON representation, used by gRPC gateways and debugging tools. Field names become lowerCamelCase, int64 becomes a string (because JavaScript cannot represent all 64-bit integers), enums become their names, Timestamp becomes an RFC 3339 string and bytes become base64. Remember this when you design contracts that must also be exposed as JSON.

Stand-in 2: ordering imports and spotting cycles

protoc loads files in dependency order and rejects cycles. This stand-in does a topological sort over an import graph and reports a cycle if there is one.

Go Stand-in: import order and cycles

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Practical layout

A layout that scales:

Text
proto/
  buf.yaml
  common/v1/money.proto
  common/v1/address.proto
  shop/v1/product.proto
  shop/v1/catalog_service.proto
  shop/v1/order.proto
  shop/v1/order_service.proto
  • One service per file, named <name>_service.proto, with messages for that service nearby or in sibling files.
  • Shared types in common/v1.
  • Keep syntax, package and options at the top; keep imports sorted.
  • Run buf lint to enforce these conventions automatically (see installing protoc and plugins).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Imports in a .proto file are resolved relative to:

    Import paths are rooted at the proto path, so shop/v1/money.proto works from any file.
  2. 2. Why put a version such as v1 in the package name?

    A new package version is the clean way to ship incompatible changes.
  3. 3. What does the go_package option do?

    Options affect generated code, not the wire format.
  4. 4. How are circular imports handled?

    protoc rejects dependency cycles.
  5. 5. How does JSON mapping represent an int64?

    Strings avoid precision loss in JavaScript, which cannot hold every 64-bit integer.

Summary

  • Packages namespace your types and appear in method paths; include a version.
  • Imports are resolved against the proto path; cycles are not allowed; import public re-exports.
  • Nested messages suit tightly coupled types; shared types belong at top level.
  • File options like go_package and java_package shape generated code but not the wire.
  • Match directory layout to package names and lint with buf.

Next: Defining Services and Unary RPCs