Whats the best way to deprecate a field in Protocol Buffer v3, reserved vs deprecated=true?

user_80389 0
Viewed 2887

When using Protocol Buffers version 3, from what I can see, there are 2 ways you can deprecate a field:

Either using the deprecate field using tags:

message MyMessage {
    string deprecated_my_field = 1 [deprecated=true];
}

Or creating a reserved field ID:

message MyMessage {
    reserved 1; // Deprecated "my_field"
}

I am leaning towards reserved since then no one will be able to use the field.

Is this a bad idea?

protocol-buffers
2 Answers

Both will work; the first option keeps the definition in the model, so it can still be accessed and queried - but it may generate a build warning when available (for clients who update from the schema). This may have useful applications in some cases.

The second option completely removes the field from the model, so any existing usages will break at build when clients update from the schema. Again, this could be good or bad, depending on how "done" you are with the field.

In some cases, the softer "mark it as a build warning, but allow access" may be preferred; in others, the hard "that doesn't exist!" approach is cleaner. It is subjective.

Either will fundamentally get the job done.

Marc_Gravell_233540

One way to view this is that using [ deprecated = true ] actually deprecates the field while using reserve actually obsoletes the field. A big difference between the two is that the latter introduces a backwards-incompatible change and, pedantically, warrants a new version of the proto.

It might also be a good idea to document the deprecated/obsoleted field (including what to use instead if applicable) with something like:

  [
    deprecated = true,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Recipient's name"
    }
  ]
user_8070370
Related