Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quickstart

nim-protobuf-serialization is a Nim library that helps you serialize your Nim objects to Protobuf 2 or 3.

Installation

Add the dependency to your .nimble file:

requires "protobuf_serialization"

Or install directly:

nimble install protobuf_serialization

Basic Usage

1. Define Your Types

Annotate your Nim types with protobuf pragmas:

import protobuf_serialization
type
  Person {.proto3.} = object
    name {.fieldNumber: 1.}: string
    age {.fieldNumber: 2, pint.}: int32
    email {.fieldNumber: 3.}: string

2. Encode and Decode

Use Protobuf.encode and Protobuf.decode to serialize your objects:

let person = Person(
  name: "Alice",
  age: 30,
  email: "alice@example.com"
)

# Encode to bytes
let encoded = Protobuf.encode(person)

# Decode back to object
let decoded = Protobuf.decode(encoded, Person)

assert decoded == person

Proto2 vs Proto3

Both Protobuf 2 and 3 semantics are supported. Add the proto2 or proto3 pragma to your object type:

type
  MessageV2 {.proto2.} = object
    id {.fieldNumber: 1, required, pint.}: int32
    text {.fieldNumber: 2.}: seq[string]

type
  MessageV3 {.proto3.} = object
    id {.fieldNumber: 1, pint.}: int32
    text {.fieldNumber: 2.}: string

Info

The required pragma is only available in proto2. This reflects the Protocol Buffers specification: proto2 supports explicit required, optional, and repeated field modifiers, while proto3 removed the required keyword entirely. In proto3, all fields are implicitly optional with default values.

Importing .proto Files

.proto files are Protocol Buffers schema definition files. They define the structure of your messages using a language-neutral, platform-neutral syntax. These files are commonly used to share message definitions across different programming languages and systems.

You might want to import .proto files when:

  • Working with existing protobuf schemas from other projects or teams
  • Ensuring compatibility with services that use standard .proto definitions
  • Avoiding manual annotation of Nim types when a schema already exists

This library can generate Nim types directly from .proto files at compile-time:

import protobuf_serialization/proto_parser

# This generates Nim types from your .proto file at compile-time
import_proto3 "my_protocol.proto3"

Info

The import_proto3 macro reads and parses the .proto file during compilation, generating equivalent Nim types. This means there's no runtime overhead—the types are fully available as if you had written them manually in Nim.

Building Documentation

Build the documentation site:

nimble docs

The docs will be generated in docs/ directory. The API docs are in docs/apidocs. Serve with any static file server, e.g.:

python3 -m http.server -d docs

Next Steps