We have a protobuf type where we added a field, and then never implemented the features using it (so it was [deprecated=true] to hint that it should not be used). Several years later, the time has come, and now we do want to use that field after all.
Is it safe to just remove the [deprecated=true] and start using the field, or is that likely to break anything?
A field with the same type and semantics already exists on another message, so it would be very nice to use the name we gave it initially, rather than adding a new field and bloating the definition with two similar fields.
Edit: The proto3 language guide section on options has this to say:
deprecated (field option): If set to true, indicates that the field is deprecated and should not be used by new code. In most languages this has no actual effect. In Java, this becomes a #Deprecated annotation. In the future, other language-specific code generators may generate deprecation annotations on the field's accessors, which will in turn cause a warning to be emitted when compiling code which attempts to use the field. If the field is not used by anyone and you want to prevent new users from using it, consider replacing the field declaration with a reserved statement.
The only thing your clients will "notice", will be the missing deprecation warning in Java that they may have been used to, if they are still using the deprecated field. All fields are optional since proto3, so this should not break anything.
Related
I noticed that they bring optional back in protobuf 3.15. I'm trying to use optional to check field presence. But I'm still unclear regarding the philosophy behind this.
Here is my usecase:
I'm providing some services that accept protobuf as my input. But the client side is untrusted from my perspective, therefore I have to check the nullability for the input protobuf.
The way I expect is that,
for a required field, either it's set, or it's null,
for an optional field, I don't care I can just use a default value and that won't cause any problem from my system
So I end up adding optional to every field that should not be null so that I can use hasXXX to check the presence. This looks weird to me because those fileds are actually required from my perspective, but I have to add optioanl keyword for them all.......I'm not sure whether this is a good practice. Proto experts pls give me some suggestions.
Also the default value doesn't make sense to me at all regarding nullability checking, since zero or empty string usually have their own meaning in many scenarios.
The entire point of optional in proto3 is to be able to distinguish between, for example:
no value was specified for field Foo
the field Foo was explicitly assigned the value that happens to be the proto3 default (zero/empty-string/false/etc)
In proto3 without optional: the above both look identical (which is to say: the field is omitted)
If you don't need to distinguish between those two scenarios: you don't need optional, but using optional also isn't likely to hurt much - worst case, a few extra zero/empty-string/false values get written to the wire, but they're small anyway.
Google's API Design guide discourages the usage of the optional keyword. Better practice is to make use of the google.api.field_behavior annotation for describing the field's behaviour.
It is however not recommended to use the optional annotation at all [1]. If one consistently implements the field behaviour annotations then OPTIONAL is redundant and can be omitted.
Check out AIP 203 for an overview of the various behaviour types along with guidelines around the usage of OPTIONAL fields.
In general, Google's API Improvement Proposals are a great reference for good practices in your API design.
I'm using protobuf (and protoc) for the first time with Go.
message MyProtoStruct {
string description = 1;
}
I'm a little bit confused:
should I use methods to get values (like MyProtoStruct.GetDescription()) or
should I use fields directly (like MyProtoStruct.Description)?
You can use either. Note that for proto2 generated code rather than proto3 (proto2 is the default), fields in protocol buffer messages are always pointers. In that case, the getters return a zero value if the field is nil. That's very convenient, since it's quite difficult to write code that uses fields directly without causing nil pointer dereferences when a field is missing.
In proto3 generated code (which I'd suggest you use, for more than one reason), I'd suggest you use fields directly. In proto2 generated code, I'd suggest using the get methods.
I have two applications that talk to eachother via GPB messages. Both were using proto3, but found out one will have to use proto2. If the messages are the same, can one program use proto2 to compile while the other uses proto3? Or do they need to be compiled with the same version of proto.
The wire format is very similar, so it will work to some extent. However, there are some caveats:
Distinction of required/optional fields does not exist on proto3. You should make all the fields optional on proto2 side to avoid errors about missing required fields.
When proto3 encodes fields, any fields that have zero value will be missing when decoded on proto2 side. If you specify zero as default value on proto2 side, it should work out ok.
Extensions and Any type will be quite difficult to use in a way that would be compatible with both.
Looking at the proto3 reference:
https://developers.google.com/protocol-buffers/docs/proto3#simple
It says this about singular:
singular: a well-formed message can have zero or one of this field (but not more than one).
It's not clear to me how this is different than optional. Is singular just an explicit way of stating that something is optional (which is now implicit for proto3)? Or is there something else this does that I'm missing?
Thanks.
Optional is proto2 syntax. Singular is proto3 syntax.
In proto3, singular is the default rule. As today the documentation needs to be improved, and there's an open issue: google/protobuf#3457.
See also google/protobuf#2497 why messge type remove 'required,optional'?, and also haberman's comment on GoogleCloudPlatform/google-cloud-python#1402:
I think the question is: what are you trying to do? Why is it relevant
to you whether a field is set or not and what do you intend to do with
this information?
In proto3, field presence for scalar fields simply doesn't exist. Your
mental model for proto3 should be that it's a C++ or Go struct. For
integers and strings, there is no such thing as being set or not, it
always has a value. For submessages, it's a pointer to the submessage
instance which can be NULL, that's why you can test presence for it.
One of the attractive features of protocol buffers is that it allows you extend the message definitions without breaking code that uses the older definition. In the case of an enum according to the documentation:
a field with an enum type can only have one of a specified set of constants as its value (if you try to provide a different value, the parser will treat it like an unknown field)
therefore if you extend the enum and use the new value then a field with that type in old code will be undefined or have its default value, if there is one.
What is a good strategy to deal with this, knowing that in future the enum may have additional values added?
One way that comes to mind is to define an "undefined" member of the enum and make that the default, then old code will know it has been sent something that it can't interpret. Is that sensible, are there better ways to deal with this situation?
Yes, the best approach is to make the first value in the enum something like UNKNOWN = 0. Then old programs reading a protobuf with an enum value they don't recognize will see it as UNKNOWN and hopefully they can handle that reasonably, eg by skipping that element.
If you want to do this you'll also want to make the enum be optional not required.
required, generally, means "I'd rather the program just abort than handle something it doesn't understand."
Note that it must be the first value declared in the proto source - just being the zero value doesn't make it the default.
At least in the java implementation of proto3, it creates a default value. The value will start with "UNKNOWN_ENUM_VALUE_"
Code references:
https://github.com/protocolbuffers/protobuf/blob/0707f2e7f556c8396d6027d0533ec3a56d1061db/java/core/src/main/java/com/google/protobuf/Descriptors.java#L640-L642
https://github.com/protocolbuffers/protobuf/blob/0707f2e7f556c8396d6027d0533ec3a56d1061db/java/core/src/main/java/com/google/protobuf/GeneratedMessageV3.java#L2750-L2751
https://github.com/protocolbuffers/protobuf/blob/0707f2e7f556c8396d6027d0533ec3a56d1061db/java/core/src/main/java/com/google/protobuf/Descriptors.java#L1832
https://github.com/protocolbuffers/protobuf/blob/0707f2e7f556c8396d6027d0533ec3a56d1061db/java/core/src/main/java/com/google/protobuf/Descriptors.java#L2034-L2045