0
# JSON Format Conversion
1

2
Complete bidirectional conversion system between protobuf messages and JSON format, supporting the Proto3 JSON mapping specification. Provides configurable options for field naming, default value handling, type registries, and output formatting.
3

4
## Capabilities
5

6
### Printer Creation
7

8
Creates a printer instance with default configurations for converting protobuf messages to JSON.
9

10
```java { .api }
11
/**
12
 * Creates a Printer with default configurations.
13
 * 
14
 * @return A new Printer instance with default settings
15
 */
16
public static JsonFormat.Printer printer();
17
```
18

19
### Parser Creation
20

21
Creates a parser instance with default configurations for converting JSON to protobuf messages.
22

23
```java { .api }
24
/**
25
 * Creates a Parser with default configuration.
26
 * 
27
 * @return A new Parser instance with default settings
28
 */
29
public static JsonFormat.Parser parser();
30
```
31

32
### Printer Configuration
33

34
Configure printer behavior for various output requirements.
35

36
```java { .api }
37
/**
38
 * Creates a new Printer using the given registry for resolving Any types.
39
 * 
40
 * @param registry TypeRegistry for resolving Any message types
41
 * @return New Printer with the specified type registry
42
 * @throws IllegalArgumentException if a registry is already set
43
 */
44
public JsonFormat.Printer usingTypeRegistry(JsonFormat.TypeRegistry registry);
45

46
/**
47
 * Creates a new Printer using the given registry for resolving Any types.
48
 * 
49
 * @param registry com.google.protobuf.TypeRegistry for resolving Any message types
50
 * @return New Printer with the specified type registry
51
 * @throws IllegalArgumentException if a registry is already set
52
 */
53
public JsonFormat.Printer usingTypeRegistry(com.google.protobuf.TypeRegistry registry);
54

55
/**
56
 * Creates a new Printer that will always print fields unless they are a message type or in a oneof.
57
 * Note: This method is deprecated.
58
 * 
59
 * @return New Printer that includes default value fields
60
 * @deprecated Use alwaysPrintFieldsWithNoPresence() instead
61
 */
62
@Deprecated
63
public JsonFormat.Printer includingDefaultValueFields();
64

65
/**
66
 * Creates a new Printer that will print specified default-valued fields.
67
 * 
68
 * @param fieldsToAlwaysOutput Set of field descriptors to always print
69
 * @return New Printer with specified default field behavior
70
 */
71
public JsonFormat.Printer includingDefaultValueFields(Set<FieldDescriptor> fieldsToAlwaysOutput);
72

73
/**
74
 * Creates a new Printer that prints fields with no presence even if default.
75
 * 
76
 * @return New Printer that prints fields without presence
77
 */
78
public JsonFormat.Printer alwaysPrintFieldsWithNoPresence();
79

80
/**
81
 * Creates a new Printer that prints enum field values as integers.
82
 * 
83
 * @return New Printer that prints enums as integers
84
 */
85
public JsonFormat.Printer printingEnumsAsInts();
86

87
/**
88
 * Creates a new Printer that uses original proto field names instead of camelCase.
89
 * 
90
 * @return New Printer that preserves proto field names
91
 */
92
public JsonFormat.Printer preservingProtoFieldNames();
93

94
/**
95
 * Creates a new Printer that omits insignificant whitespace in JSON output.
96
 * 
97
 * @return New Printer that produces compact JSON
98
 */
99
public JsonFormat.Printer omittingInsignificantWhitespace();
100

101
/**
102
 * Creates a new Printer that sorts map keys in JSON output.
103
 * 
104
 * @return New Printer that sorts map keys
105
 */
106
public JsonFormat.Printer sortingMapKeys();
107
```
108

109
### Message to JSON Conversion
110

111
Convert protobuf messages to JSON format with various output options.
112

113
```java { .api }
114
/**
115
 * Converts a protobuf message to Proto3 JSON format.
116
 * 
117
 * @param message The protobuf message to convert
118
 * @param output The output destination for JSON
119
 * @throws InvalidProtocolBufferException if message contains unresolvable Any types
120
 * @throws IOException if writing to output fails
121
 */
122
public void appendTo(MessageOrBuilder message, Appendable output) throws IOException;
123

124
/**
125
 * Converts a protobuf message to Proto3 JSON format as a string.
126
 * 
127
 * @param message The protobuf message to convert
128
 * @return JSON string representation of the message
129
 * @throws InvalidProtocolBufferException if message contains unresolvable Any types
130
 */
131
public String print(MessageOrBuilder message) throws InvalidProtocolBufferException;
132
```
133

134
### Parser Configuration
135

136
Configure parser behavior for handling various JSON input formats.
137

138
```java { .api }
139
/**
140
 * Creates a new Parser using the given registry for resolving Any types.
141
 * 
142
 * @param registry TypeRegistry for resolving Any message types
143
 * @return New Parser with the specified type registry
144
 * @throws IllegalArgumentException if a registry is already set
145
 */
146
public JsonFormat.Parser usingTypeRegistry(JsonFormat.TypeRegistry registry);
147

148
/**
149
 * Creates a new Parser using the given registry for resolving Any types.
150
 * 
151
 * @param registry com.google.protobuf.TypeRegistry for resolving Any message types
152
 * @return New Parser with the specified type registry
153
 * @throws IllegalArgumentException if a registry is already set
154
 */
155
public JsonFormat.Parser usingTypeRegistry(com.google.protobuf.TypeRegistry registry);
156

157
/**
158
 * Creates a new Parser that ignores unknown fields instead of throwing exceptions.
159
 * 
160
 * @return New Parser that ignores unknown fields
161
 */
162
public JsonFormat.Parser ignoringUnknownFields();
163
```
164

165
### JSON to Message Conversion
166

167
Parse JSON strings into protobuf message builders.
168

169
```java { .api }
170
/**
171
 * Parses Proto3 JSON format into a protobuf message.
172
 * 
173
 * @param json JSON string to parse
174
 * @param builder Message builder to populate
175
 * @throws InvalidProtocolBufferException if JSON is invalid or contains unknown fields
176
 */
177
public void merge(String json, Message.Builder builder) throws InvalidProtocolBufferException;
178

179
/**
180
 * Parses Proto3 JSON from a Reader into a protobuf message.
181
 * 
182
 * @param json Reader containing JSON data
183
 * @param builder Message builder to populate
184
 * @throws InvalidProtocolBufferException if JSON is invalid or contains unknown fields
185
 * @throws IOException if reading from input fails
186
 */
187
public void merge(Reader json, Message.Builder builder) throws IOException;
188
```
189

190
### Type Registry Management
191

192
Manage type registries for resolving Any message types during JSON conversion.
193

194
```java { .api }
195
/**
196
 * Returns an empty TypeRegistry.
197
 * 
198
 * @return Empty TypeRegistry instance
199
 */
200
public static JsonFormat.TypeRegistry getEmptyTypeRegistry();
201

202
/**
203
 * Creates a new TypeRegistry builder.
204
 * 
205
 * @return New TypeRegistry.Builder instance
206
 */
207
public static JsonFormat.TypeRegistry.Builder newBuilder();
208

209
/**
210
 * Finds a type by its full name.
211
 * 
212
 * @param name Full name of the message type
213
 * @return Descriptor for the type, or null if not found
214
 */
215
public Descriptor find(String name);
216
```
217

218
### Type Registry Builder
219

220
Build type registries with message types for Any resolution.
221

222
```java { .api }
223
/**
224
 * Adds a message type and all transitively imported types to the registry.
225
 * 
226
 * @param messageType Message descriptor to add
227
 * @return This builder for method chaining
228
 */
229
public JsonFormat.TypeRegistry.Builder add(Descriptor messageType);
230

231
/**
232
 * Adds multiple message types and all transitively imported types to the registry.
233
 * 
234
 * @param messageTypes Iterable of message descriptors to add
235
 * @return This builder for method chaining
236
 */
237
public JsonFormat.TypeRegistry.Builder add(Iterable<Descriptor> messageTypes);
238

239
/**
240
 * Builds the TypeRegistry.
241
 * 
242
 * @return New TypeRegistry instance
243
 */
244
public JsonFormat.TypeRegistry build();
245
```
246

247
**Usage Examples:**
248

249
```java
250
import com.google.protobuf.util.JsonFormat;
251
import com.google.protobuf.InvalidProtocolBufferException;
252

253
// Basic JSON conversion
254
JsonFormat.Printer printer = JsonFormat.printer();
255
String jsonString = printer.print(myMessage);
256

257
JsonFormat.Parser parser = JsonFormat.parser();
258
MyMessage.Builder builder = MyMessage.newBuilder();
259
parser.merge(jsonString, builder);
260
MyMessage parsed = builder.build();
261

262
// Custom printer configuration
263
JsonFormat.Printer customPrinter = JsonFormat.printer()
264
    .preservingProtoFieldNames()
265
    .omittingInsignificantWhitespace()
266
    .printingEnumsAsInts();
267

268
String compactJson = customPrinter.print(myMessage);
269

270
// Parser with unknown field handling
271
JsonFormat.Parser tolerantParser = JsonFormat.parser()
272
    .ignoringUnknownFields();
273

274
MyMessage.Builder tolerantBuilder = MyMessage.newBuilder();
275
tolerantParser.merge(jsonWithExtraFields, tolerantBuilder);
276

277
// Type registry for Any types
278
JsonFormat.TypeRegistry typeRegistry = JsonFormat.TypeRegistry.newBuilder()
279
    .add(MyCustomMessage.getDescriptor())
280
    .add(AnotherMessage.getDescriptor())
281
    .build();
282

283
JsonFormat.Printer anyPrinter = JsonFormat.printer()
284
    .usingTypeRegistry(typeRegistry);
285

286
JsonFormat.Parser anyParser = JsonFormat.parser()
287
    .usingTypeRegistry(typeRegistry);
288
```