JSON Writer - Haufe-Lexware/haufe.no-frills-transformation GitHub Wiki
The JSON Writer plugin enables writing transformation results to JSON files. It automatically constructs nested JSON structures from dot-notation field names.
The JSON Writer recognizes the following URI formats:
-
json://<filepath>- Write to a JSON file -
file://<filepath>.json- Write to a JSON file (must have.jsonextension)
Example:
<Target>file://output.json</Target>The JSON Writer always produces a JSON array containing all records:
[
{ /* record 1 */ },
{ /* record 2 */ },
{ /* record 3 */ }
]The JSON Writer converts dot-notation field names into nested JSON objects:
Field Mappings:
-
firstName→ "John" -
lastName→ "Doe"
Output:
[
{
"firstName": "John",
"lastName": "Doe"
}
]Field Mappings:
-
user.name→ "John Doe" -
user.email→ "[email protected]" -
user.age→ "30"
Output:
[
{
"user": {
"name": "John Doe",
"email": "[email protected]",
"age": "30"
}
}
]Field Mappings:
-
company.name→ "Acme Corp" -
company.contact.email→ "[email protected]" -
company.contact.phone→ "555-1234" -
company.address.city→ "Springfield"
Output:
[
{
"company": {
"name": "Acme Corp",
"contact": {
"email": "[email protected]",
"phone": "555-1234"
},
"address": {
"city": "Springfield"
}
}
}
]The JSON Writer automatically omits properties with empty string values and removes nested objects that become empty:
Field Mappings:
-
id→ "123" -
name→ "John" -
email→ "" (empty) -
address.street→ "" (empty) -
address.city→ "" (empty)
Output:
[
{
"id": "123",
"name": "John"
}
]Note: Both email and the entire address object are omitted because they are empty.
The JSON Writer validates field names at initialization and throws errors for invalid configurations:
<!-- This will throw an error -->
<Transformation>
<Source config="delim=';'">file://source.csv</Source>
<Target>json://output.json</Target>
<Fields>
<Field name="user">$Field1</Field>
<Field name="user.name">$Field2</Field>
</Fields>
</Transformation>Error: Cannot have both 'user' and 'user.name' as property and subproperty.
You cannot have both a simple property and nested subproperties with the same name.
<!-- This will throw an error -->
<Fields>
<Field name="items.1">...</Field>
<Field name="items.2">...</Field>
</Fields>Error: Arrays are not supported in JSON output: 'items.1'
The JSON Writer does not support creating arrays. Numeric property names are not allowed.
<!-- This will throw an error -->
<Fields>
<Field name="user..name">...</Field>
</Fields>Error: Invalid field name: 'user..name'
Property names cannot be empty (no consecutive dots allowed).
<Fields>
<Field name="id">$Id</Field>
<Field name="name">$Name</Field>
<Field name="contact.email">$ContactEmail</Field>
<Field name="contact.phone">$ContactPhone</Field>
<Field name="address.street">$ContactStreet</Field>
<Field name="address.city">$ContactCity</Field>
<Field name="address.zip">$ContactZip</Field>
</Fields>[
{
"id": "1",
"name": "Acme Corp",
"contact": {
"email": "[email protected]",
"phone": "555-1234"
},
"address": {
"street": "123 Main St",
"city": "Springfield",
"zip": "12345"
}
},
{
"id": "2",
"name": "TechStart Inc",
"contact": {
"email": "[email protected]"
}
}
]Note: In the second record, the contact.phone and entire address object are omitted because they were empty.
The output JSON is always formatted with indentation for readability:
- 2-space indentation
- Each property on its own line
- Standard UTF-8 encoding
- No array support: You cannot create JSON arrays as output values. The writer only supports objects.
- All values are strings: Input values are not parsed for type information. Numbers, booleans, and null values are all written as strings.
- In-memory processing: All records are collected in memory before writing to disk.
-
Field names are case-sensitive:
User.Nameanduser.nameare treated as different properties. - No duplicate properties: Each field name must be unique; you cannot write the same property multiple times.