TransformScript reads and writes a variety of structured business and integration formats. You select a format using a format directive (a MIME type or an alias), and you can optionally supply format properties such as delimiters, headers, or indentation to control how data is read or written.

Using Input and Output Formats

In TransformScript, "input" and "output" are the format of the file you're transforming and the format you want to produce. You control the output explicitly in the script header, and TransformScript uses the same format identifiers (aliases or MIME types) consistently in both directions.

How Input Works

TransformScript starts with the current file's contents as the input. That input is exposed to your script as payload. The input format determines the shape of payload:

JSON: payload is a JSON object, array, or scalar.
CSV: payload is an array of rows (objects when headers are present, arrays when they aren't).
XML: payload is a structured XML tree representation you can traverse.
X12, EDIFACT, or HL7: payload is a structured representation of segments and elements.

The input directive is optional. When the header declares an input format, that wins and TransformScript reads the raw bytes accordingly. When the header omits input, TransformScript auto-detects the format from the file's extension and reads it with that. An already-parsed native value is passed through unchanged either way.

Extension detection covers the common cases:

Extension(s)	Detected format
`.json`	json
`.ndjson`, `.jsonl`	ndjson
`.yaml`, `.yml`	yaml
`.xml`	xml
`.csv`	csv
`.tsv`	csv with a tab separator
`.xlsx`	xlsx
`.hl7`	hl7
`.x12`	x12
`.edifact`	edifact

So in most Automations you don't need to write an input directive at all. A .csv file is read as CSV automatically. Declare input explicitly only when you want to override the detected format or pass format properties (for example input csv header=false). If a file's extension isn't one of the above and no input directive is given, the transform fails with a message that names the undetected filename.

How Output Works

You declare output in the script header:

%files 1.0
output json
---
{ ok: true }

The output directive does two things. It tells TransformScript which format to write your script's result in, and it defines the output file format along with optional output properties like pretty, header, or delimiter.

The value after --- is the data you're producing, usually an object or array. TransformScript then writes that data into the declared output format.

Properties Apply to the Direction You're Using

The same format identifier is used for both reading and writing. Properties apply to whichever side is relevant:

For CSV output, properties like header=true, delimiter="|", and lineSeparator="\n" control how the CSV is written.
For CSV input, those same properties (when supplied on the input side) control how the CSV is read, for example whether the first row is treated as a header.

Examples

CSV to JSON

%files 1.0
output application/json
---
payload map (r) -> {
  id: r.CustomerID,
  email: r.Email
}

JSON to CSV (With Header Row)

%files 1.0
output application/csv header=true delimiter=","
---
payload.users map (u) -> {
  UserID: u.id,
  Email: u.email
}

JSON to NDJSON (One Line Per Entry)

%files 1.0
output application/x-ndjson lineSeparator="\n"
---
payload.events

Properties

You can append key/value properties to tune reading or writing. For example:

format=csv header=false delimiter="|"
format=application/json pretty=true indentation=2

Property names are case-sensitive. Values may be:

bare tokens like true, false, null, 1, 1.5
quoted strings like "|" or "\n"

Encoding

All formats support an encoding=<charset> property. The default is UTF-8, and output is encoded using the requested charset. If an unknown charset is provided, the transform fails with an "unsupported encoding" error.

Supported Formats

JSON (json, application/json)

Use for APIs, webhooks, SaaS exports, and general structured documents. The data shape is objects, arrays, and scalar values (string, number, boolean, null).

Properties:

pretty / indent (boolean, default false): enable pretty-printed JSON
indentation (integer, default 2): spaces per nesting level when pretty-printing
encoding (string, default UTF-8)

Newline-Delimited JSON (ndjson, application/x-ndjson, application/ndjson)

Use for logs, event streams, and bulk exports. The data shape is an array of JSON values; each array element is written as one JSON object per line.

Properties:

All JSON properties (pretty, indentation, encoding)
lineSeparator (string, default "\n"): line terminator (must be non-empty)

Behavior notes:

Output typically ends with a trailing line separator.
Readers commonly tolerate a final blank line.

YAML (yaml, application/x-yaml, application/yaml, text/yaml)

Use for configuration-like documents and human-readable exports. The data shape is YAML-compatible objects, arrays, and scalars.

Properties:

indentation (integer, default 2)
lineWidth (integer, default -1, meaning no wrapping)
canonical (boolean, default false)
documentStart (boolean, default false): emit a leading ---
documentEnd (boolean, default false): emit a trailing ...
encoding (string, default UTF-8)

CSV (csv, application/csv, text/csv)

Use for spreadsheets, partner feeds, and finance or ops exports and imports. The data shape is an array of rows. Each row is either an object row (key/value pairs, with column names taken from keys) or a positional row (an array of values). Do not mix object rows and positional rows in the same output.

Properties:

header (boolean; default depends on row type):
- object rows: default true
- positional rows: default false
separator / delimiter (string, default ","): column delimiter (must be non-empty)
lineSeparator (string, default "\n"): row terminator (must be non-empty)
forceQuotes (boolean, default false): quote every cell
encoding (string, default UTF-8)

Behavior notes:

When writing object rows, the header row is derived from the output keys.

XML (xml, application/xml)

Use for ERP imports, partner integrations, and document-style payloads. The data shape is a hierarchical XML structure (elements with attributes, text, and children).

Properties:

pretty / indent (boolean, default false)
indentation (integer, default 2)
onInvalidChar (none | ignore | base64, default none): handling for characters not allowed in XML
escapeGT (boolean, default false)
escapeCR (boolean, default false)
inlineCloseOn (empty | none, default empty): whether empty elements use <tag/> (empty) or <tag></tag> (none)
encoding (string, default UTF-8)

URL-Encoded Form (urlencoded, application/x-www-form-urlencoded)

Use for legacy web APIs and simple form posts. The data shape is key/value pairs. Values may be scalars or arrays (arrays expand into repeated keys).

Properties:

encoding (string, default UTF-8)

HL7 v2 (ER7) (hl7, application/hl7-v2, x-application/hl7-v2+er7)

Use for healthcare HL7 v2 message exchange. The data shape is a sequence of segments with delimited fields, including repeats and components.

Default separators:

Field: |
Component: ^
Repeat: ~
Subcomponent: &
Escape: \
Segment terminator: carriage return

Properties:

fieldSeparator, componentSeparator, repeatSeparator, subcomponentSeparator, escapeCharacter, segmentTerminator (single-character strings)
encoding (string, default UTF-8)

EDIFACT (edifact, application/edifact, application/edi-edifact)

Use for EDIFACT trading partner integrations. The data shape is a sequence of segments; each segment contains ordered elements, including composites.

Properties:

componentSeparator (char, default ":")
dataSeparator (char, default "+")
decimalMark (char, default ".")
releaseCharacter (char, default "?")
segmentTerminator (char, default "'")
repetitionSeparator (char or null, default null)
emitUna (boolean, default auto): when enabled, writes a UNA segment reflecting the delimiter set
encoding (string, default UTF-8)

ANSI X12 (x12, application/edi-x12, application/x12)

Use for X12 trading partner integrations. The data shape is a sequence of segments; each segment contains ordered elements, including composites.

Properties:

elementSeparator (char, default "*")
componentSeparator (char, default ":")
segmentTerminator (char, default "~")
releaseCharacter (char, default "?")
repetitionSeparator (char or unset)
syncIsaSeparators (boolean, default true): keep the ISA segment separator fields consistent with configured separators
encoding (string, default UTF-8)

For more on building transforms and working with these formats, see Writing a TransformScript, EDI and Business Documents, and Differences from DataWeave. To return to the overview, see the TransformScript landing page.