Skip to content

Commit 5f8b6f1

Browse files
Protocol Buffer TeamLogofile
Protocol Buffer Team
authored and
Logofile
committed
This documentation change includes the following:
* Adds an overview to the 1-1-1 Best Practice topic * Adds a paragraph about explicit presence to the nullable-getters-setters.md topic * Updates the version-tables.css topic to reflect the current state of version support * Adds the release dates to all of the version-specific news topics * Clarifies some content and corrects a method name in the Editions.md topic * Clarifies some content in the encoding.md topic * Adds a topic about MIME types PiperOrigin-RevId: 766670574 Change-Id: I806dc5684bc1ee2807ea1bd3bc692befb2dcd067
1 parent 30abe78 commit 5f8b6f1

File tree

15 files changed

+109
-34
lines changed

15 files changed

+109
-34
lines changed

‎content/best-practices/1-1-1.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@ type = "docs"
77
aliases = "/programming-guides/1-1-1"
88
+++
99

10+
The "1-1-1" best practice advocates structuring definitions with one top-level
11+
entity (message, enum, or extension) per `.proto` file, corresponding to a
12+
single `proto_library` build rule. This approach promotes small, modular proto
13+
definitions. Key benefits include simplified refactoring, potentially improved
14+
build times, and smaller binary sizes due to minimized transitive dependencies.
15+
16+
--------------------------------------------------------------------------------
17+
1018
The 1-1-1 best practice is to keep every proto_library and .proto file as small
1119
as is reasonable, with the ideal being:
1220

‎content/design-decisions/nullable-getters-setters.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ C#, and Rust). While this does seem to be a helpful feature for folks using
1212
those languages, the design choice has tradeoffs which have led to the Protobuf
1313
team choosing not to implement them.
1414

15+
Explicit presence is not a concept that directly maps to the traditional notion
16+
of nullability. It is subtle, but explicit presence philosophy is closer to "the
17+
fields are not nullable, but you can detect if the field was explicitly assigned
18+
a value or not. Normal access will see some default value if it is not assigned,
19+
but you can check if the field was actively written to or not, when needed."
20+
1521
The biggest reason not to have nullable fields is the intended behavior of
1622
default values specified in a `.proto` file. By design, calling a getter on an
1723
unset field will return the default value of that field.

‎content/includes/version-tables.css

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -95,36 +95,36 @@ table.version-chart td.active {
9595
/* latest release column */
9696
/*
9797
* How to advance the selection of the latest release:
98-
* Replace class 'y25q1' in the following selectors with 'y25q2' (the class
98+
* Replace class 'y25q2' in the following selectors with 'y25q3' (the class
9999
* referring to the quarter of the next release). Please also update this
100100
* instruction as a courtesy to the next maintainer.
101101
*/
102102

103103
/* visually replace 'yyQq' heading with string 'Latest' */
104-
table.version-chart th.y25q1 span {
104+
table.version-chart th.y25q2 span {
105105
display: none;
106106
}
107-
table.version-chart th.y25q1::after {
107+
table.version-chart th.y25q2::after {
108108
content: "Latest"
109109
}
110110

111111
/* draw a focus rectangle around the latest release column */
112-
table.version-chart th.y25q1 {
112+
table.version-chart th.y25q2 {
113113
border-top: 2px solid #e06666 !important;
114114
border-left: 2px solid #e06666 !important;
115115
border-right: 2px solid #e06666 !important;
116116
}
117-
table.version-chart td.y25q1 {
117+
table.version-chart td.y25q2 {
118118
font-weight: bold;
119119
border-left: 2px solid #e06666 !important;
120120
border-right: 2px solid #e06666 !important;
121121
}
122-
table.version-chart tr:last-child td.y25q1 {
122+
table.version-chart tr:last-child td.y25q2 {
123123
border-bottom: 2px solid #e06666 !important;
124124
}
125125

126126
/* future release columns */
127-
table.version-chart td:not(:has(~ .y25q1)):not(.y25q1) {
127+
table.version-chart td:not(:has(~ .y25q2)):not(.y25q2) {
128128
font-style: italic;
129129
}
130130

‎content/news/v21.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 21.x."
66
type = "docs"
77
+++
88

9-
The following announcements are specific to Version 21.x. For information
10-
presented chronologically, see [News](/news).
9+
The following announcements are specific to Version 21.x, which was released May
10+
25, 2022. For information presented chronologically, see
11+
[News](/news).
1112

1213
## Python Updates {#python-updates}
1314

‎content/news/v22.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 22.x."
66
type = "docs"
77
+++
88

9-
The following announcements are specific to Version 22.x. For information
10-
presented chronologically, see [News](/news).
9+
The following announcements are specific to Version 22.x, which was released
10+
February 16, 2023. For information presented chronologically, see
11+
[News](/news).
1112

1213
### Changing Maven Release Candidate Artifact Names to Be More Idiomatic {#idiomatic}
1314

‎content/news/v23.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 23.x."
66
type = "docs"
77
+++
88

9-
The following announcements are specific to Version 23.x. For information
10-
presented chronologically, see [News](/news).
9+
The following announcements are specific to Version 23.x, which was released May
10+
8, 2023. For information presented chronologically, see
11+
[News](/news).
1112

1213
## Changes to Ruby Generator {#ruby}
1314

‎content/news/v24.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 24.x."
66
type = "docs"
77
+++
88

9-
The following announcements are specific to Version 24.x. For information
10-
presented chronologically, see [News](/news).
9+
The following announcements are specific to Version 24.x, which was released
10+
August 8, 2023. For information presented chronologically, see
11+
[News](/news).
1112

1213
## Stricter validation for `json_name` {#json-name}
1314

‎content/news/v25.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 25.x."
66
type = "docs"
77
+++
88

9-
The following announcements are specific to Version 25.x. For information
10-
presented chronologically, see [News](/news).
9+
The following announcements are specific to Version 25.x, which was released
10+
November 1, 2023. For information presented chronologically, see
11+
[News](/news).
1112

1213
## Python Breaking Change
1314

‎content/news/v26.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 26.x."
66
type = "docs"
77
+++
88

9-
The following announcements are specific to Version 26.x. For information
10-
presented chronologically, see [News](/news).
9+
The following announcements are specific to Version 26.x, which was released
10+
March 13, 2024. For information presented chronologically, see
11+
[News](/news).
1112

1213
## General Changes
1314

‎content/news/v29.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 29.x."
66
type = "docs"
77
+++
88

9-
The following announcements are specific to Version 29.x. For information
10-
presented chronologically, see [News](/news).
9+
The following announcements are specific to Version 29.x, which was released
10+
November 27, 2024. For information presented chronologically, see
11+
[News](/news).
1112

1213
## Bazel and Proto Rules
1314

‎content/news/v30.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 30.x."
66
type = "docs"
77
+++
88

9-
The following announcements are specific to Version 30.x. For information
10-
presented chronologically, see [News](/news).
9+
The following announcements are specific to Version 30.x, which was released
10+
March 4, 2025. For information presented chronologically, see
11+
[News](/news).
1112

1213
The following sections cover planned breaking changes in the v30 release,
1314
expected in 2025 Q1. Also included are some changes that aren't breaking but may

‎content/news/v31.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ description = "Changes announced for Protocol Buffers version 31.x."
66
type = "docs"
77
+++
88

9-
The following announcements are specific to Version 31.x. For information
10-
presented chronologically, see [News](/news).
9+
The following announcements are specific to Version 31.x, which was released May
10+
14, 2025. For information presented chronologically, see
11+
[News](/news).
1112

1213
The following sections cover planned breaking changes in the v31 release,
1314
expected in 2025 Q2. Also included are some changes that aren't breaking but may

‎content/programming-guides/editions.md

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1028,15 +1028,16 @@ following rules:
10281028
preserved in the message, but how this is represented when the message is
10291029
deserialized is language-dependent. Int fields always just preserve their
10301030
value.
1031-
* Changing a single `optional` field or extension into a member of a **new**
1031+
* Changing a *single* `optional` field or extension into a member of a **new**
10321032
`oneof` is binary compatible, however for some languages (notably, Go) the
10331033
generated code's API will change in incompatible ways. For this reason,
10341034
Google does not make such changes in its public APIs, as documented in
10351035
[AIP-180](https://google.aip.dev/180#moving-into-oneofs). With
1036-
the same caveat about source-compatibility, moving multiple fields into a
1037-
new `oneof` may be safe if you are sure that no code sets more than one at a
1038-
time. Moving fields into an existing `oneof` is not safe. Likewise, changing
1039-
a single field `oneof` to an `optional` field or extension is safe.
1036+
the same caveat about source-compatibility, moving *multiple* fields into a
1037+
**new** `oneof` may be safe if you are sure that no code sets more than one
1038+
at a time. Likewise, changing a *single* field `oneof` to an `optional`
1039+
field or extension is safe. Moving *any* fields into an **existing** `oneof`
1040+
is **not** safe.
10401041
* Changing a field between a `map<K, V>` and the corresponding `repeated`
10411042
message field is binary compatible (see [Maps](#maps), below, for the
10421043
message layout and other restrictions). However, the safety of the change is
@@ -1183,8 +1184,8 @@ In C++, it would look something like:
11831184
```cpp
11841185
UserContent user_content;
11851186
user_content.AddExtension(kittens::kitten_videos, new kittens::Video());
1186-
assert(1 == user_content.GetExtensionCount(kittens::kitten_videos));
1187-
user_content.GetExtension(kittens::kitten_videos, 0);
1187+
assert(1 == user_content.GetRepeatedExtension(kittens::kitten_videos).size());
1188+
user_content.GetRepeatedExtension(kittens::kitten_videos)[0];
11881189
```
11891190
11901191
### Defining Extension Ranges {#defining-ranges}

‎content/programming-guides/encoding.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -423,8 +423,9 @@ message Test6 {
423423
}
424424
```
425425

426-
Thus, maps are encoded exactly like a `repeated` message field: as a sequence of
427-
`LEN`-typed records, with two fields each.
426+
Thus, maps are encoded almost exactly like a `repeated` message field: as a
427+
sequence of `LEN`-typed records, with two fields each. The exception is that
428+
order is not guaranteed to be preserved with maps during serialization.
428429

429430
## Groups {#groups}
430431

‎content/reference/protobuf/mime-types.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
+++
2+
title = "Protocol Buffer MIME Types"
3+
weight = 830
4+
linkTitle = "MIME Types"
5+
description = "Standard MIME types for Protobuf Serializations."
6+
type = "docs"
7+
+++
8+
9+
All Protobuf documents should have the MIME type `application` and the subtype
10+
`protobuf`, with the suffix `+json` for
11+
JSON
12+
encodings according to
13+
[the standard](https://datatracker.ietf.org/doc/draft-murray-dispatch-mime-protobuf/),
14+
followed by the following parameters:
15+
16+
- `encoding` should be set only to `binary`,
17+
or `json`, denoting those respective
18+
formats.
19+
+ With subtype `protobuf+json`, `encoding` has the default `json` and
20+
cannot be set to `binary`. With subtype `protobuf` (without `+json`),
21+
`encoding` has the default `binary` and cannot be set to
22+
`json`.
23+
+ Use `+json` for JSON even in HTTP responses that use parser
24+
breakers as a CORB mitigation.
25+
- Set `charset` to `utf-8` for all JSONor Text Format encodings, and never set
26+
it for binary encodings.
27+
+ If `charset` is unspecified it is assumed to be UTF-8. It is preferable
28+
to always specify a `charset` as that may prevent certain attack vectors
29+
when protos are used in HTTP responses.
30+
- Protobuf reserves the `version` parameter for potential future versioning of
31+
our wire formats. Do not set it until a wire format is versioned.
32+
33+
So the standard MIME types for common protobuf encodings are:
34+
35+
- `application/protobuf` for serialized binary protos.
36+
- `application/protobuf+json; charset=utf-8` for JSON format protos.
37+
38+
Services that read Protobuf should also handle `application/json`, which may be
39+
used to encode JSON format protos.
40+
41+
Parsers must fail if MIME parameters (`encoding`, `charset`, or `version`) have
42+
unknown or illegal values.
43+
44+
When binary protos are transacted over HTTP, Protobuf strongly recommends
45+
Base64-encoding them and setting `X-Content-Type-Options: nosniff` to prevent
46+
XSS, as it is possible for a Protobuf to parse as active content.
47+
48+
It is acceptable to pass additional parameters to these MIME types if desired,
49+
such as a type URL which indicates the content schema; but the MIME type
50+
parameters ***must not*** include encoding options.

0 commit comments

Comments
 (0)