zig-protobuf

# zig-protobuf

<img src="logo.svg" width="50%">


## State of the implementation

This repository implements [protocol buffers](https://protobuf.dev/) for `proto2`, `proto3` and
[editions](https://protobuf.dev/editions/overview/) (up to edition 2026), including [extensions](#extensions).

This project is mature enough to be used in production. It passes the upstream
[conformance suite](conformance/) (protobuf v36.2) for the proto2, proto3 and editions test messages, in binary and JSON. The text format is not supported.

## Editions

Editions replace the `syntax` keyword with fine grained *features*, which can be set for a
whole file or for individual fields and enums. `proto2` and `proto3` are handled as the
legacy editions they correspond to, so the same rules apply to all three. The generator
resolves the features of every element and maps them to Zig as follows:

| Feature | Zig representation |
| --- | --- |
| `field_presence = EXPLICIT` | optional field `?T = null`. The `[default = ...]` value is in `defaults`. Refer to [Default values](#default-values) |
| `field_presence = IMPLICIT` | plain field `T` holding the zero value, which is not serialized |
| `field_presence = LEGACY_REQUIRED` | plain field `T`, always serialized. It has its `[default = ...]` value if it declares one |
| `enum_type = OPEN` | non-exhaustive enum (`_`), unknown values are kept |
| `enum_type = CLOSED` | exhaustive enum, unknown values are stored as unknown fields |
| `repeated_field_encoding` | `.packed_repeated` or `.repeated` field descriptor |
| `message_encoding = DELIMITED` | `fdf(n, .submessage, .{ .message_encoding = .delimited })`, encoded as a group |
| `utf8_validation = VERIFY` | `fdf(n, .{ .scalar = .string }, .{ .utf8_validation = .verify })`, invalid strings fail to decode |

```proto
edition = "2023";

message Example {
  int32 explicit = 1;                                          // ?i32 = null
  int32 implicit = 2 [features.field_presence = IMPLICIT];     // i32 = 0
  Nested nested = 3 [features.message_encoding = DELIMITED];   // encoded as a group
}
```

The in-development `edition = "UNSTABLE"` is rejected by default, as its features may change
in any protobuf release. To accept it, set `.experimental_editions = true` in the options of
`RunProtocStep`, which passes `--experimental_editions` to protoc and to the generator.

## Default values

> **CAUTION:** This behavior is different from the behavior of previous versions.
> Previous versions set optional fields to their `[default = ...]` value.
> Examine your code before you update. Refer also to [Update from version 5](#update-from-version-5).

### Presence and value

A field with explicit presence has two properties:

1. Its presence. The field is set or not set.
2. Its value. A set field has the value that it holds. A field that is not set has its default value.

In Zig, an optional field (`?T`) holds the two properties. The value `null` shows that the field is not set.

### Encoding

The en