https://protobuf.dev/programming-guides/Recent content in Programming Guides on Protocol Buffers DocumentationHugoenhttps://protobuf.dev/programming-guides/editions/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/editions/This guide describes how to use the protocol buffer language to structure your protocol buffer data, including .proto file syntax and how to generate data access classes from your .proto files. It covers edition 2023 to edition 2024 of the protocol buffers language. For information about how editions differ from proto2 and proto3 conceptually, see Protobuf Editions Overview. For information on the proto2 syntax, see the Proto2 Language Guide. For information on proto3 syntax, see the Proto3 Language Guide.https://protobuf.dev/programming-guides/proto2/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/proto2/This guide describes how to use the protocol buffer language to structure your protocol buffer data, including .proto file syntax and how to generate data access classes from your .proto files. It covers the proto2 revision of the protocol buffers language. For information on editions syntax, see the Protobuf Editions Language Guide. For information on proto3 syntax, see the Proto3 Language Guide. This is a reference guide – for a step by step example that uses many of the features described in this document, see the tutorial for your chosen language.https://protobuf.dev/programming-guides/proto3/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/proto3/This guide describes how to use the protocol buffer language to structure your protocol buffer data, including .proto file syntax and how to generate data access classes from your .proto files. It covers the proto3 revision of the protocol buffers language. For information on editions syntax, see the Protobuf Editions Language Guide. For information on the proto2 syntax, see the Proto2 Language Guide. This is a reference guide – for a step by step example that uses many of the features described in this document, see the tutorial for your chosen language.https://protobuf.dev/programming-guides/proto-limits/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/proto-limits/This topic documents the limits to the number of supported elements (fields, enum values, and so on) in proto schemas. This information is a collection of discovered limitations by many engineers, but is not exhaustive and may be incorrect/outdated in some areas. As you discover limitations in your work, contribute those to this document to help others. Number of Fields All messages are limited to 65,535 fields. Message with only singular proto fields (such as Boolean):https://protobuf.dev/programming-guides/style/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/style/This document provides a style guide for .proto files. By following these conventions, you’ll make your protocol buffer message definitions and their corresponding classes consistent and easy to read. Enforcement of the following style guidelines is controlled via enforce_naming_style. Standard File Formatting Keep the line length to 80 characters. Use an indent of 2 spaces. Prefer the use of double quotes for strings. File Structure Files should be named lower_snake_case.proto.https://protobuf.dev/programming-guides/enum/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/enum/Enums behave differently in different language libraries. This topic covers the different behaviors as well as the plans to move protobufs to a state where they are consistent across all languages. If you’re looking for information on how to use enums in general, see the corresponding sections in the proto2, proto3, and editions 2023 language guide topics. Definitions Enums have two distinct flavors (open and closed). They behave identically except in their handling of unknown values.https://protobuf.dev/programming-guides/encoding/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/encoding/This document describes the protocol buffer wire format, which defines the details of how your message is sent on the wire and how much space it consumes on disk. You probably don’t need to understand this to use protocol buffers in your application, but it’s useful information for doing optimizations. If you already know the concepts but want a reference, skip to the Condensed reference card section. Protoscope is a very simple language for describing snippets of the low-level wire format, which we’ll use to provide a visual reference for the encoding of various messages.https://protobuf.dev/programming-guides/json/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/json/Protobuf supports a canonical encoding in JSON, making it easier to share data with systems that do not support the standard protobuf binary wire format. This page specifies the format, but a number of additional edge cases which define a conformant ProtoJSON parser are covered in the Protobuf Conformance Test Suite and are not exhaustively detailed here. Non-goals of the Format Cannot Represent Some JSON schemas The ProtoJSON format is designed to be a JSON representation of schemas which are expressible in the Protobuf schema language.https://protobuf.dev/programming-guides/techniques/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/techniques/You can also send design and usage questions to the Protocol Buffers discussion group. Common Filename Suffixes It is fairly common to write messages to files in several different formats. We recommend using the following file extensions for these files. Content Extension Text Format .txtpb Wire Format .binpb JSON Format .json For Text Format specifically, .textproto is also fairly common, but we recommend .txtpb for its brevity. Streaming Multiple Messages If you want to write multiple messages to a single file or stream, it is up to you to keep track of where one message ends and the next begins.https://protobuf.dev/programming-guides/addons/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/addons/Many open source projects seek to add useful functionality on top of Protocol Buffers. For a list of links to projects we know about, see the third-party add-ons wiki page.https://protobuf.dev/programming-guides/extension_declarations/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/extension_declarations/Introduction This page describes in detail what extension declarations are, why we need them, and how we use them. Note Proto3 does not support extensions (except for declaring custom options). Extensions are fully supported in proto2 and editions though. If you need an introduction to extensions, read this extensions guide Motivation Extension declarations aim to strike a happy medium between regular fields and extensions. Like extensions, they avoid creating a dependency on the message type of the field, which therefore results in a leaner build graph and smaller binaries in environments where unused messages are difficult or impossible to strip.https://protobuf.dev/programming-guides/field_presence/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/field_presence/Background Field presence is the notion of whether a protobuf field has a value. There are two different manifestations of presence for protobufs: implicit presence, where the generated message API stores field values (only), and explicit presence, where the API also stores whether or not a field has been set. Note We recommend always adding the optional label for proto3 basic types. This provides a smoother path to editions, which uses explicit presence by default.https://protobuf.dev/programming-guides/symbol_visibility/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/symbol_visibility/This document describes the terminology and functionality of the symbol visibility system introduced in proto edition = "2024" Glossary Symbol: Any of message, enum, service or extend <type>, the allowed Top-Level types in a .proto file. Top-Level: A Symbol defined at the root of a .proto file. This includes all service definitions and any message, enum, or extend block not nested in message. Visibility: Property of a Symbol that controls whether it can be imported into another .https://protobuf.dev/programming-guides/serialization-not-canonical/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/serialization-not-canonical/Many people want a serialized proto to canonically represent the contents of that proto. Use cases include: using a serialized proto as a key in a hash table taking a fingerprint or checksum of a serialized proto comparing serialized payloads as a way of checking message equality Unfortunately, protobuf serialization is not (and cannot be) canonical. There are a few notable exceptions, such as MapReduce, but in general you should generally think of proto serialization as unstable.https://protobuf.dev/programming-guides/deserialize-debug/Mon, 01 Jan 0001 00:00:00 +0000https://protobuf.dev/programming-guides/deserialize-debug/From version 30.x, Protobuf DebugString APIs (Message::DebugString, Message::ShortDebugString, Message::Utf8DebugString), additional Protobuf APIs (proto2::ShortFormat, proto2::Utf8Format), Abseil string functions (such as absl::StrCat, absl::StrFormat, absl::StrAppend, and absl::Substitute), and Abseil logging API will begin to automatically convert proto arguments into a new debugging format . See the related announcement here. Unlike the Protobuf DebugString output format, the new debugging format automatically redacts sensitive fields by replacing their values with the string “[REDACTED]” (without the quotation marks).