|
|
@@ -7,74 +7,6 @@ we recommend using protoc's Ruby generation support with .proto files. The
|
|
|
build process in this directory only installs the extension; you need to
|
|
|
install protoc as well to have Ruby code generation functionality.
|
|
|
|
|
|
-JSON Migration Note
|
|
|
--------------------
|
|
|
-
|
|
|
-Users who were using the protobuf Gem `<= 3.0.0.alpha.5.0.4` will notice that
|
|
|
-the JSON format has changed slightly and is incompatible with previous
|
|
|
-versions.
|
|
|
-
|
|
|
-The change concerns field names. Prior to the change, field names from the
|
|
|
-.proto file were used verbatim. Take this `.proto` file:
|
|
|
-
|
|
|
-```protobuf
|
|
|
-syntax = "proto3";
|
|
|
-
|
|
|
-message M {
|
|
|
- int32 my_int_field = 1;
|
|
|
- bool my_bool_field = 2;
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-Serializing to JSON used to give you something like this:
|
|
|
-
|
|
|
-```json
|
|
|
-{"my_int_field":1, "my_bool_field":true}
|
|
|
-```
|
|
|
-
|
|
|
-However this format was not compatible with the proto3 JSON spec. To be
|
|
|
-compliant with proto3 JSON, we need to camel-case the names:
|
|
|
-
|
|
|
-```json
|
|
|
-{"myIntField":1, "myBoolField":true}
|
|
|
-```
|
|
|
-
|
|
|
-Starting with `3.0.0.alpha.5.0.5`, this bug was fixed and we now produce the
|
|
|
-correct camelCased names. However this may cause compatibility problems for
|
|
|
-JSON users who can't upgrade everything at the same time, or who store
|
|
|
-serialized JSON payloads. To mitigate this and allow time for migration, the
|
|
|
-library currently recognizes two environment variables:
|
|
|
-
|
|
|
- - `UPB_JSON_ACCEPT_LEGACY_FIELD_NAMES`: set this variable to instruct the
|
|
|
- JSON parser that the old names should be accepted in addition to the new,
|
|
|
- compliant ones. This will make the parser compatible with both formats.
|
|
|
- - `UPB_JSON_WRITE_LEGACY_FIELD_NAMES`: set this variable to instruct the
|
|
|
- JSON serializer to encode the old, non-compliant names.
|
|
|
-
|
|
|
-These options will be removed in a future version of Ruby protobuf. All
|
|
|
-users shoud migrate to the standard names.
|
|
|
-
|
|
|
-If users have existing payloads in the old format and cannot easily migrate,
|
|
|
-the best solution would be to specify the old names explicitly in the
|
|
|
-`.proto` file using the `json_name` option. For example, for the .proto
|
|
|
-file above, the user could specify:
|
|
|
-
|
|
|
-```protobuf
|
|
|
-syntax = "proto3";
|
|
|
-
|
|
|
-message M {
|
|
|
- int32 my_int_field = 1 [json_name="my_int_field"];
|
|
|
- bool my_bool_field = 2 [json_name="my_bool_field"];
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-This will make all compliant proto3 JSON parsers/serializers use the
|
|
|
-non-camel-cased names forever. Note that protobuf Ruby does *not yet*
|
|
|
-support this option properly, but support is forthcoming. It will
|
|
|
-certainly be supported before the environment variables above are
|
|
|
-removed.
|
|
|
-
|
|
|
-
|
|
|
Installation from Gem
|
|
|
---------------------
|
|
|
|
Josh Haberman