0
# Format Conversion
1

2
Bidirectional conversion utilities between YAML and JSON formats using Jackson's processing capabilities. Provides static utility methods for format transformation without requiring parser or builder instances.
3

4
## Capabilities
5

6
### YamlConverter Class
7

8
Static utility class providing bidirectional conversion between YAML and JSON formats.
9

10
```java { .api }
11
/**
12
 * A converter for converting YAML to JSON, and vice versa.
13
 * Uses Jackson libraries internally for robust format handling.
14
 */
15
public final class YamlConverter {
16
    // Private constructor - utility class with static methods only
17
}
18
```
19

20
### Convert YAML to JSON
21

22
Convert YAML content from a Reader to JSON string format.
23

24
```java { .api }
25
/**
26
 * Convert yaml to json.
27
 * @param yamlReader the reader of yaml content
28
 * @return the text of json
29
 * @throws YamlRuntimeException if conversion fails
30
 */
31
public static String convertYamlToJson(Reader yamlReader);
32
```
33

34
**Usage Example:**
35

36
```java
37
import org.apache.groovy.yaml.util.YamlConverter;
38
import java.io.StringReader;
39

40
String yamlContent = """
41
name: example
42
version: 1.0.0
43
dependencies:
44
  - groovy
45
  - jackson
46
""";
47

48
String jsonResult = YamlConverter.convertYamlToJson(new StringReader(yamlContent));
49
// jsonResult will be: {"name":"example","version":"1.0.0","dependencies":["groovy","jackson"]}
50
```
51

52
**Multiple Document Handling:**
53

54
```java
55
import org.apache.groovy.yaml.util.YamlConverter;
56
import java.io.StringReader;
57

58
String multiDocYaml = """
59
---
60
name: doc1
61
---
62
name: doc2
63
---
64
name: doc3
65
""";
66

67
String jsonResult = YamlConverter.convertYamlToJson(new StringReader(multiDocYaml));
68
// Multiple YAML documents are converted to a JSON array
69
// jsonResult will be: [{"name":"doc1"},{"name":"doc2"},{"name":"doc3"}]
70
```
71

72
### Convert JSON to YAML
73

74
Convert JSON content from a Reader to YAML string format.
75

76
```java { .api }
77
/**
78
 * Convert json to yaml.
79
 * @param jsonReader the reader of json content
80
 * @return the text of yaml
81
 * @throws YamlRuntimeException if conversion fails
82
 */
83
public static String convertJsonToYaml(Reader jsonReader);
84
```
85

86
**Usage Example:**
87

88
```java
89
import org.apache.groovy.yaml.util.YamlConverter;
90
import java.io.StringReader;
91

92
String jsonContent = """
93
{
94
  "name": "example",
95
  "version": "1.0.0",
96
  "dependencies": ["groovy", "jackson"]
97
}
98
""";
99

100
String yamlResult = YamlConverter.convertJsonToYaml(new StringReader(jsonContent));
101
// yamlResult will be:
102
// ---
103
// name: "example"
104
// version: "1.0.0"
105
// dependencies:
106
// - "groovy"
107
// - "jackson"
108
```
109

110
**Array Conversion:**
111

112
```java
113
import org.apache.groovy.yaml.util.YamlConverter;
114
import java.io.StringReader;
115

116
String jsonArray = """
117
[
118
  {"name": "item1", "value": 1},
119
  {"name": "item2", "value": 2}
120
]
121
""";
122

123
String yamlResult = YamlConverter.convertJsonToYaml(new StringReader(jsonArray));
124
// yamlResult will be:
125
// ---
126
// - name: "item1"
127
//   value: 1
128
// - name: "item2"
129
//   value: 2
130
```
131

132
## Integration with Other Components
133

134
### With YamlSlurper
135

136
Use YamlConverter in conjunction with YamlSlurper for advanced processing:
137

138
```java
139
import groovy.yaml.YamlSlurper;
140
import org.apache.groovy.yaml.util.YamlConverter;
141
import java.io.StringReader;
142

143
// Convert JSON to YAML, then parse with YamlSlurper
144
String jsonContent = """{"name": "example", "items": [1, 2, 3]}""";
145
String yamlContent = YamlConverter.convertJsonToYaml(new StringReader(jsonContent));
146

147
YamlSlurper yamlSlurper = new YamlSlurper();
148
Object result = yamlSlurper.parseText(yamlContent);
149
```
150

151
### With YamlBuilder
152

153
Use YamlConverter with YamlBuilder for round-trip conversions:
154

155
```groovy
156
import groovy.yaml.YamlBuilder
157
import org.apache.groovy.yaml.util.YamlConverter
158
import java.io.StringReader
159

160
// Build YAML, convert to JSON, then back to YAML
161
def yamlBuilder = new YamlBuilder()
162
yamlBuilder {
163
    name "example"
164
    items([1, 2, 3])
165
}
166

167
String originalYaml = yamlBuilder.toString()
168
String jsonVersion = YamlConverter.convertYamlToJson(new StringReader(originalYaml))
169
String roundTripYaml = YamlConverter.convertJsonToYaml(new StringReader(jsonVersion))
170
```
171

172
## Error Handling
173

174
Both conversion methods throw `YamlRuntimeException` if the input format is invalid or conversion fails:
175

176
```java { .api }
177
public class YamlRuntimeException extends GroovyRuntimeException {
178
    public YamlRuntimeException(String msg);
179
    public YamlRuntimeException(Throwable cause);
180
    public YamlRuntimeException(String msg, Throwable cause);
181
}
182
```
183

184
**Example Error Handling:**
185

186
```java
187
import org.apache.groovy.yaml.util.YamlConverter;
188
import groovy.yaml.YamlRuntimeException;
189
import java.io.StringReader;
190

191
try {
192
    String invalidJson = "{invalid json content";
193
    String result = YamlConverter.convertJsonToYaml(new StringReader(invalidJson));
194
} catch (YamlRuntimeException e) {
195
    System.err.println("Conversion failed: " + e.getMessage());
196
    // Handle conversion error
197
}
198
```
199

200
## Implementation Notes
201

202
- Uses Jackson YAML (`com.fasterxml.jackson.dataformat.yaml.YAMLFactory`) for YAML processing
203
- Uses Jackson Databind (`com.fasterxml.jackson.databind.ObjectMapper`) for JSON processing
204
- Automatically handles single documents vs. multi-document YAML files
205
- Maintains data type fidelity during conversion
206
- Supports complex nested structures including arrays and objects