Skip to content

Commit ae0c43c

Browse files
Updates textformat-spec.md to add Editions information.
PiperOrigin-RevId: 816418404
1 parent 8fce3a0 commit ae0c43c

File tree

1 file changed

+38
-7
lines changed

1 file changed

+38
-7
lines changed

content/reference/protobuf/textformat-spec.md

Lines changed: 38 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -371,7 +371,9 @@ repeated_field: [1, 2, 3, 4, 5, 6, 7, 8, 9]
371371
Non-`repeated` fields cannot use the list syntax. For example, `[0]` is not
372372
valid for `optional` or `required` fields. Fields marked `optional` can be
373373
omitted or specified once. Fields marked `required` must be specified exactly
374-
once.
374+
once. `required` is a legacy feature of proto2 and is not available in proto3.
375+
Backward compatibility is available for messages in Editions using
376+
[`features.field_presence = LEGACY_REQUIRED`](/editions/features#field_presence).
375377

376378
Fields not specified in the associated *.proto* message are not allowed unless
377379
the field name is present in the message's `reserved` field list. `reserved`
@@ -561,9 +563,10 @@ stores a serialized `com.example.SomeType` message containing `field1: hello`.
561563

562564
In text format, a `group` field uses a normal `MessageValue` element as its
563565
value, but is specified using the capitalized group name rather than the
564-
implicit lowercased field name. Example:
566+
implicit lower-cased field name. Example:
565567

566568
```proto
569+
// proto2
567570
message MessageWithGroup {
568571
optional group MyGroup = 1 {
569572
optional int32 my_value = 1;
@@ -583,15 +586,40 @@ MyGroup {
583586
Similar to Message fields, the `:` delimiter between the group name and value is
584587
optional.
585588

589+
This functionality is included in Editions for backward-compatibility. Normally
590+
`DELIMITED` fields will serialize like normal messages. The following shows the
591+
behavior with Editions:
592+
593+
```proto
594+
edition = "2024";
595+
596+
message Parent {
597+
message GroupLike {
598+
int32 foo = 1;
599+
}
600+
GroupLike grouplike = 1 [features.message_encoding = DELIMITED];
601+
}
602+
```
603+
604+
The content of that *.proto* file will be serialized like a proto2 group:
605+
606+
```proto
607+
GroupLike {
608+
foo: 2;
609+
}
610+
```
611+
586612
## `map` Fields {#map}
587613

588614
Text format does not provide a custom syntax for specifying map field entries.
589-
When a [`map`](/programming-guides/proto2#maps) field is
590-
defined in a *.proto* file, an implicit `Entry` message is defined containing
591-
`key` and `value` fields. Map fields are always repeated, accepting multiple
592-
key/value entries. Example:
615+
When a `map` field is defined in a *.proto* file, an implicit `Entry` message is
616+
defined containing `key` and `value` fields. Map fields are always repeated,
617+
accepting multiple key/value entries. Example:
593618

594619
```proto
620+
// Editions
621+
edition = "2024";
622+
595623
message MessageWithMap {
596624
map<string, int32> my_map = 1;
597625
}
@@ -624,9 +652,12 @@ one `oneof` member may be specified at a time. Specifying multiple members
624652
concurrently is not valid. Example:
625653

626654
```proto
655+
// Editions
656+
edition = "2024";
657+
627658
message OneofExample {
628659
message MessageWithOneof {
629-
optional string not_part_of_oneof = 1;
660+
string not_part_of_oneof = 1;
630661
oneof Example {
631662
string first_oneof_field = 2;
632663
string second_oneof_field = 3;

0 commit comments

Comments
 (0)