Optional mentioned as default field rule in proto3 documentation

[JulyGitH]

Hello,

I'm learning about ProtoBuf and writing a POC with proto3 as protobuf syntax. While browsing the doc about Proto3 syntax and the Internet, I found some inconsistencies.
The documentation ProtobufDoc speaks of these 4 field rules : singular, optional, repeated and map, singular being the default field rule.

However, in an issue on gitHub here, it is said that optional has been removed as a field rule, and I understood that it was now the default rule (which is also claimed by both VSCode and WebStorm when I work with it).

I don't find it clear which are the proto3 field rules, and which one is the default one : is it singular ? is it optional ? And if both are still in use in proto3, what is the difference between them ?

I'm sorry if this is a duplicate, I did not found an issue about the presence of optional and singular in proto3 doc or the fact that both are claimed to be the default rule.
Thanks a lot for all the work.

Julie

[esorot]

For Proto3, the required keyword was completely dropped mainly because the feature made evolving a proto file nearly impossible. By default, now all fields are "optional" meaning that they can be sent over the wire or not and it wouldn't cause a problem. This behavior is similar to the optional keyword in Proto2.
Proto3 reused the optional keyword. However, in Proto3, the usage of optional causes the generator to generate the "hassers" API. These can be used for checking field presence(has a field been set or not).
Hopefully this helps to clarify things.

[Logofile]

We expanded the documentation in this area back in September, but it seems we have some more work to do to clarify the different use cases. Thank you for the thorough write-up about the confusion you're experiencing... it helps me to pinpoint the content that we need to fix/expand/enhance. I'll update this issue once we've pushed an update to the topic.

[JulyGitH]

Hello to both of you,

Thanks for your replies, and the explanations. @esorot thanks for theses precisions, it made things a bit clearer, but I'm still confused about the singular rule, which is said to be the default rule. Is it still used ? Or is optional preferred to this rule ?

Thanks again and have a nice day.

Julie

[esorot]

So "singular" might be the confusing thing here. It's really referring to a basic field(Not a Map or Repeated Field). It's the default rule because a user doesn't have to add any additional modifiers to a field for a field to be "singular". Think primitive vs arrays and maps.

int, float, string, etc - these are primitive fields and thus "singular"

optional - this is a field modifier, which can be applied to primitive fields or Messages. optional cannot be used with map or repeated fields. Marking a field optional will generate additional APIs for checking if a field has been set or not. Without marking a field optional, your client code wouldn't be able to tell the different between a field being set or if it's using the default value.

Example:

syntax = "proto3";

message FooProto {
  map<string, string> mymap = 1;
  repeated int32 repeated_int = 2;

  // Singular fields
  int32 foo = 3; // not able to tell the difference between default value for int32 and not set. No presence tracking
  optional int32 foo_optional = 4; // HasFooOptional(): True - has been set, False - not set. Explicit tracking for presence
  BarProto bar = 5; // No presence tracking
  optional BarProto bar_optional = 6; // Explicit tracking
}

message BarProto {
  int32 bar = 1; // No presence tracking
}

[JulyGitH]

I think I get it now ! So singular, repeated and map are field rules, and optional is a modifier which can only be applied to singular fields, that's it ?
And if I want a field to be optional, not just singular, I should add the optional keyword?
My IDEs scream at me when I do, pretending it's the default field, but may be they do so because they're using proto2 syntax doc...

Really, thanks again for these explainations, it seems much more clear to me now!