diff --git a/content/best-practices/1-1-1.md b/content/best-practices/1-1-1.md index acf459733..7f5fcc935 100644 --- a/content/best-practices/1-1-1.md +++ b/content/best-practices/1-1-1.md @@ -7,6 +7,14 @@ type = "docs" aliases = "/programming-guides/1-1-1" +++ +The "1-1-1" best practice advocates structuring definitions with one top-level +entity (message, enum, or extension) per `.proto` file, corresponding to a +single `proto_library` build rule. This approach promotes small, modular proto +definitions. Key benefits include simplified refactoring, potentially improved +build times, and smaller binary sizes due to minimized transitive dependencies. + +-------------------------------------------------------------------------------- + The 1-1-1 best practice is to keep every proto_library and .proto file as small as is reasonable, with the ideal being: diff --git a/content/design-decisions/nullable-getters-setters.md b/content/design-decisions/nullable-getters-setters.md index c0a427d23..858f9a6fa 100644 --- a/content/design-decisions/nullable-getters-setters.md +++ b/content/design-decisions/nullable-getters-setters.md @@ -12,6 +12,12 @@ C#, and Rust). While this does seem to be a helpful feature for folks using those languages, the design choice has tradeoffs which have led to the Protobuf team choosing not to implement them. +Explicit presence is not a concept that directly maps to the traditional notion +of nullability. It is subtle, but explicit presence philosophy is closer to "the +fields are not nullable, but you can detect if the field was explicitly assigned +a value or not. Normal access will see some default value if it is not assigned, +but you can check if the field was actively written to or not, when needed." + The biggest reason not to have nullable fields is the intended behavior of default values specified in a `.proto` file. By design, calling a getter on an unset field will return the default value of that field. diff --git a/content/includes/version-tables.css b/content/includes/version-tables.css index d694c1c5b..6e18e3dce 100644 --- a/content/includes/version-tables.css +++ b/content/includes/version-tables.css @@ -95,36 +95,36 @@ table.version-chart td.active { /* latest release column */ /* * How to advance the selection of the latest release: - * Replace class 'y25q1' in the following selectors with 'y25q2' (the class + * Replace class 'y25q2' in the following selectors with 'y25q3' (the class * referring to the quarter of the next release). Please also update this * instruction as a courtesy to the next maintainer. */ /* visually replace 'yyQq' heading with string 'Latest' */ -table.version-chart th.y25q1 span { +table.version-chart th.y25q2 span { display: none; } -table.version-chart th.y25q1::after { +table.version-chart th.y25q2::after { content: "Latest" } /* draw a focus rectangle around the latest release column */ -table.version-chart th.y25q1 { +table.version-chart th.y25q2 { border-top: 2px solid #e06666 !important; border-left: 2px solid #e06666 !important; border-right: 2px solid #e06666 !important; } -table.version-chart td.y25q1 { +table.version-chart td.y25q2 { font-weight: bold; border-left: 2px solid #e06666 !important; border-right: 2px solid #e06666 !important; } -table.version-chart tr:last-child td.y25q1 { +table.version-chart tr:last-child td.y25q2 { border-bottom: 2px solid #e06666 !important; } /* future release columns */ -table.version-chart td:not(:has(~ .y25q1)):not(.y25q1) { +table.version-chart td:not(:has(~ .y25q2)):not(.y25q2) { font-style: italic; } diff --git a/content/news/v21.md b/content/news/v21.md index b19970043..4634ec40f 100644 --- a/content/news/v21.md +++ b/content/news/v21.md @@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 21.x." type = "docs" +++ -The following announcements are specific to Version 21.x. For information -presented chronologically, see [News](/news). +The following announcements are specific to Version 21.x, which was released May +25, 2022. For information presented chronologically, see +[News](/news). ## Python Updates {#python-updates} diff --git a/content/news/v22.md b/content/news/v22.md index 042652409..23b1fdca4 100644 --- a/content/news/v22.md +++ b/content/news/v22.md @@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 22.x." type = "docs" +++ -The following announcements are specific to Version 22.x. For information -presented chronologically, see [News](/news). +The following announcements are specific to Version 22.x, which was released +February 16, 2023. For information presented chronologically, see +[News](/news). ### Changing Maven Release Candidate Artifact Names to Be More Idiomatic {#idiomatic} diff --git a/content/news/v23.md b/content/news/v23.md index 66efa3194..c33eb9026 100644 --- a/content/news/v23.md +++ b/content/news/v23.md @@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 23.x." type = "docs" +++ -The following announcements are specific to Version 23.x. For information -presented chronologically, see [News](/news). +The following announcements are specific to Version 23.x, which was released May +8, 2023. For information presented chronologically, see +[News](/news). ## Changes to Ruby Generator {#ruby} diff --git a/content/news/v24.md b/content/news/v24.md index fb1cd577f..4fd1b15fb 100644 --- a/content/news/v24.md +++ b/content/news/v24.md @@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 24.x." type = "docs" +++ -The following announcements are specific to Version 24.x. For information -presented chronologically, see [News](/news). +The following announcements are specific to Version 24.x, which was released +August 8, 2023. For information presented chronologically, see +[News](/news). ## Stricter validation for `json_name` {#json-name} diff --git a/content/news/v25.md b/content/news/v25.md index d6471380f..30d57201a 100644 --- a/content/news/v25.md +++ b/content/news/v25.md @@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 25.x." type = "docs" +++ -The following announcements are specific to Version 25.x. For information -presented chronologically, see [News](/news). +The following announcements are specific to Version 25.x, which was released +November 1, 2023. For information presented chronologically, see +[News](/news). ## Python Breaking Change diff --git a/content/news/v26.md b/content/news/v26.md index d9b48231e..8c5697218 100644 --- a/content/news/v26.md +++ b/content/news/v26.md @@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 26.x." type = "docs" +++ -The following announcements are specific to Version 26.x. For information -presented chronologically, see [News](/news). +The following announcements are specific to Version 26.x, which was released +March 13, 2024. For information presented chronologically, see +[News](/news). ## General Changes diff --git a/content/news/v29.md b/content/news/v29.md index c0834b4a0..a4bfe9bec 100644 --- a/content/news/v29.md +++ b/content/news/v29.md @@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 29.x." type = "docs" +++ -The following announcements are specific to Version 29.x. For information -presented chronologically, see [News](/news). +The following announcements are specific to Version 29.x, which was released +November 27, 2024. For information presented chronologically, see +[News](/news). ## Bazel and Proto Rules diff --git a/content/news/v30.md b/content/news/v30.md index f35755b01..b3b0871f3 100644 --- a/content/news/v30.md +++ b/content/news/v30.md @@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 30.x." type = "docs" +++ -The following announcements are specific to Version 30.x. For information -presented chronologically, see [News](/news). +The following announcements are specific to Version 30.x, which was released +March 4, 2025. For information presented chronologically, see +[News](/news). The following sections cover planned breaking changes in the v30 release, expected in 2025 Q1. Also included are some changes that aren't breaking but may diff --git a/content/news/v31.md b/content/news/v31.md index 0c26f6c17..91944be3a 100644 --- a/content/news/v31.md +++ b/content/news/v31.md @@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 31.x." type = "docs" +++ -The following announcements are specific to Version 31.x. For information -presented chronologically, see [News](/news). +The following announcements are specific to Version 31.x, which was released May +14, 2025. For information presented chronologically, see +[News](/news). The following sections cover planned breaking changes in the v31 release, expected in 2025 Q2. Also included are some changes that aren't breaking but may diff --git a/content/programming-guides/editions.md b/content/programming-guides/editions.md index 95052ecf7..3f44e7f75 100644 --- a/content/programming-guides/editions.md +++ b/content/programming-guides/editions.md @@ -1028,15 +1028,16 @@ following rules: preserved in the message, but how this is represented when the message is deserialized is language-dependent. Int fields always just preserve their value. -* Changing a single `optional` field or extension into a member of a **new** +* Changing a *single* `optional` field or extension into a member of a **new** `oneof` is binary compatible, however for some languages (notably, Go) the generated code's API will change in incompatible ways. For this reason, Google does not make such changes in its public APIs, as documented in [AIP-180](https://google.aip.dev/180#moving-into-oneofs). With - the same caveat about source-compatibility, moving multiple fields into a - new `oneof` may be safe if you are sure that no code sets more than one at a - time. Moving fields into an existing `oneof` is not safe. Likewise, changing - a single field `oneof` to an `optional` field or extension is safe. + the same caveat about source-compatibility, moving *multiple* fields into a + **new** `oneof` may be safe if you are sure that no code sets more than one + at a time. Likewise, changing a *single* field `oneof` to an `optional` + field or extension is safe. Moving *any* fields into an **existing** `oneof` + is **not** safe. * Changing a field between a `map` and the corresponding `repeated` message field is binary compatible (see [Maps](#maps), below, for the message layout and other restrictions). However, the safety of the change is @@ -1183,8 +1184,8 @@ In C++, it would look something like: ```cpp UserContent user_content; user_content.AddExtension(kittens::kitten_videos, new kittens::Video()); -assert(1 == user_content.GetExtensionCount(kittens::kitten_videos)); -user_content.GetExtension(kittens::kitten_videos, 0); +assert(1 == user_content.GetRepeatedExtension(kittens::kitten_videos).size()); +user_content.GetRepeatedExtension(kittens::kitten_videos)[0]; ``` ### Defining Extension Ranges {#defining-ranges} diff --git a/content/programming-guides/encoding.md b/content/programming-guides/encoding.md index 3a7c05264..2a44879f1 100644 --- a/content/programming-guides/encoding.md +++ b/content/programming-guides/encoding.md @@ -423,8 +423,9 @@ message Test6 { } ``` -Thus, maps are encoded exactly like a `repeated` message field: as a sequence of -`LEN`-typed records, with two fields each. +Thus, maps are encoded almost exactly like a `repeated` message field: as a +sequence of `LEN`-typed records, with two fields each. The exception is that +order is not guaranteed to be preserved with maps during serialization. ## Groups {#groups} diff --git a/content/reference/protobuf/mime-types.md b/content/reference/protobuf/mime-types.md new file mode 100644 index 000000000..b290d4a19 --- /dev/null +++ b/content/reference/protobuf/mime-types.md @@ -0,0 +1,50 @@ ++++ +title = "Protocol Buffer MIME Types" +weight = 830 +linkTitle = "MIME Types" +description = "Standard MIME types for Protobuf Serializations." +type = "docs" ++++ + +All Protobuf documents should have the MIME type `application` and the subtype +`protobuf`, with the suffix `+json` for +JSON +encodings according to +[the standard](https://datatracker.ietf.org/doc/draft-murray-dispatch-mime-protobuf/), +followed by the following parameters: + +- `encoding` should be set only to `binary`, + or `json`, denoting those respective + formats. + + With subtype `protobuf+json`, `encoding` has the default `json` and + cannot be set to `binary`. With subtype `protobuf` (without `+json`), + `encoding` has the default `binary` and cannot be set to + `json`. + + Use `+json` for JSON even in HTTP responses that use parser + breakers as a CORB mitigation. +- Set `charset` to `utf-8` for all JSONor Text Format encodings, and never set + it for binary encodings. + + If `charset` is unspecified it is assumed to be UTF-8. It is preferable + to always specify a `charset` as that may prevent certain attack vectors + when protos are used in HTTP responses. +- Protobuf reserves the `version` parameter for potential future versioning of + our wire formats. Do not set it until a wire format is versioned. + +So the standard MIME types for common protobuf encodings are: + +- `application/protobuf` for serialized binary protos. +- `application/protobuf+json; charset=utf-8` for JSON format protos. + +Services that read Protobuf should also handle `application/json`, which may be +used to encode JSON format protos. + +Parsers must fail if MIME parameters (`encoding`, `charset`, or `version`) have +unknown or illegal values. + +When binary protos are transacted over HTTP, Protobuf strongly recommends +Base64-encoding them and setting `X-Content-Type-Options: nosniff` to prevent +XSS, as it is possible for a Protobuf to parse as active content. + +It is acceptable to pass additional parameters to these MIME types if desired, +such as a type URL which indicates the content schema; but the MIME type +parameters ***must not*** include encoding options.