@@ -7,74 +7,6 @@ we recommend using protoc's Ruby generation support with .proto files. The
7
7
build process in this directory only installs the extension; you need to
8
8
install protoc as well to have Ruby code generation functionality.
9
9
10
- JSON Migration Note
11
- -------------------
12
-
13
- Users who were using the protobuf Gem ` <= 3.0.0.alpha.5.0.4 ` will notice that
14
- the JSON format has changed slightly and is incompatible with previous
15
- versions.
16
-
17
- The change concerns field names. Prior to the change, field names from the
18
- .proto file were used verbatim. Take this ` .proto ` file:
19
-
20
- ``` protobuf
21
- syntax = "proto3";
22
-
23
- message M {
24
- int32 my_int_field = 1;
25
- bool my_bool_field = 2;
26
- }
27
- ```
28
-
29
- Serializing to JSON used to give you something like this:
30
-
31
- ``` json
32
- {"my_int_field" :1 , "my_bool_field" :true }
33
- ```
34
-
35
- However this format was not compatible with the proto3 JSON spec. To be
36
- compliant with proto3 JSON, we need to camel-case the names:
37
-
38
- ``` json
39
- {"myIntField" :1 , "myBoolField" :true }
40
- ```
41
-
42
- Starting with ` 3.0.0.alpha.5.0.5 ` , this bug was fixed and we now produce the
43
- correct camelCased names. However this may cause compatibility problems for
44
- JSON users who can't upgrade everything at the same time, or who store
45
- serialized JSON payloads. To mitigate this and allow time for migration, the
46
- library currently recognizes two environment variables:
47
-
48
- - ` UPB_JSON_ACCEPT_LEGACY_FIELD_NAMES ` : set this variable to instruct the
49
- JSON parser that the old names should be accepted in addition to the new,
50
- compliant ones. This will make the parser compatible with both formats.
51
- - ` UPB_JSON_WRITE_LEGACY_FIELD_NAMES ` : set this variable to instruct the
52
- JSON serializer to encode the old, non-compliant names.
53
-
54
- These options will be removed in a future version of Ruby protobuf. All
55
- users shoud migrate to the standard names.
56
-
57
- If users have existing payloads in the old format and cannot easily migrate,
58
- the best solution would be to specify the old names explicitly in the
59
- ` .proto ` file using the ` json_name ` option. For example, for the .proto
60
- file above, the user could specify:
61
-
62
- ``` protobuf
63
- syntax = "proto3";
64
-
65
- message M {
66
- int32 my_int_field = 1 [json_name="my_int_field"];
67
- bool my_bool_field = 2 [json_name="my_bool_field"];
68
- }
69
- ```
70
-
71
- This will make all compliant proto3 JSON parsers/serializers use the
72
- non-camel-cased names forever. Note that protobuf Ruby does * not yet*
73
- support this option properly, but support is forthcoming. It will
74
- certainly be supported before the environment variables above are
75
- removed.
76
-
77
-
78
10
Installation from Gem
79
11
---------------------
80
12
0 commit comments