Spec Version:

Transformation YAML Reference Beta

Complete YAML reference for transformation and transformation-library resources managed with Rudder CLI.

Available Plans

free
growth
enterprise

7 minute read

This guide provides a complete YAML reference for managing transformation resources using Rudder CLI.

Overview

You can define transformation resources in YAML files anywhere inside your CLI project directory. Rudder CLI scans the project recursively and processes valid resource files.

Supported resource kinds for this workflow:

transformation
transformation-library

Transformation resource

Use kind: transformation to define a transformation.

`spec` properties

Property	Type	Description
`id` Required	String	Unique project ID for the transformation.
`name` Required	String	Human-readable name. Must be non-empty.
`language` Required	String	Transformation language. Allowed values: `javascript`, `python`.
`description`	String	Optional description.
`code`	String	Inline transformation code containing valid syntax for the selected language. Mutually exclusive with `file`.
`file`	String	Path to transformation code file. Note that: The referenced file must exist and be readable. Relative paths are resolved from the YAML spec’s parent directory. One of `code` or `file` is required.
`tests`	Array	Optional list of local test suites. These tests are used only by `rudder-cli transformations test` and are not synced to workspace state during `rudder-cli apply`.

`tests` properties

Property	Type	Description
`name` Required	String	Test suite name. Must be non-empty and can contain only letters, numbers, spaces, `_`, `-`, and `/`.
`input`	String	Directory with JSON input payload files. Relative paths resolve from the spec directory. If omitted, default is `./input`.
`output`	String	Directory with expected output JSON files. Relative paths resolve from the spec directory. If omitted, default is `./output`.

Rudder CLI tests the transformation using default RudderStack events if:
spec.tests is not configured, or
No input JSON files are found in the specified input path

Validation rules

Transformation imports must resolve to existing transformation libraries

semantic error

Rule ID: transformations/transformation/semantic-valid

Examples

Transformation without library imports is valid

Code that imports nothing has no library references to resolve, so the rule passes.

spec.yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  id: my-transformation
  name: My Transformation
  language: javascript
  code: |
    export function transformEvent(event, metadata) {
      event.properties.processed = true;
      return event;
    }

Transformation imports a missing library

The code imports a library handle with no matching library resource in the project, so the import cannot be resolved.

spec.yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  id: my-transformation
  name: My Transformation
  language: javascript
  code: |
    import mathUtils from 'mathUtils';
    export function transformEvent(event, metadata) {
      event.properties.value = mathUtils.round(event.properties.value);
      return event;
    }

Diagnostics

spec.yaml /code 'mathUtils' imported library not found

Transformation spec syntax must be valid

syntactic error

Rule ID: transformations/transformation/spec-syntax-valid

Examples

Valid transformation spec with inline JavaScript

spec.yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  id: my-transformation
  name: My Transformation
  description: Enriches events with additional metadata
  language: javascript
  code: |
    export function transformEvent(event, metadata) {
      event.properties.enriched = true;
      return event;
    }

Transformation spec missing required id

spec.yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  name: My Transformation
  language: javascript
  code: |
    export function transformEvent(event, metadata) {
      return event;
    }

Diagnostics

spec.yaml /id 'id' is required

Transformation spec missing the required language

spec.yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  id: my-transformation
  name: My Transformation
  code: |
    export function transformEvent(event, metadata) {
      return event;
    }

Diagnostics

spec.yaml /language 'language' is required

Transformation spec defined with an unsupported language

spec.yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  id: my-transformation
  name: My Transformation
  language: ruby
  code: |
    def transform_event(event, metadata)
      event
    end

Diagnostics

spec.yaml /language 'language' must be one of [javascript python]

Transformation spec missing code and file

spec.yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  id: my-transformation
  name: My Transformation
  language: javascript

Diagnostics

spec.yaml /code 'code' is required when 'file' is not specified
spec.yaml /file 'file' is required when 'code' is not specified

Transformation library resource

Use kind: transformation-library to define a reusable transformation library.

`spec` properties

Property	Type	Description
`id` Required	String	Unique project ID for the library.
`name` Required	String	Human-readable name — must be non-empty.
`description`	String	Optional description.
`language` Required	String	Library language. Allowed values are `javascript` and `python`.
`code`	String	Inline library code containing valid syntax for the selected language. Mutually exclusive with `file`.
`file`	String	Path to library code file. Note that: The referenced file must exist and be readable. Relative paths are resolved from the YAML spec’s parent directory. One of `code` or `file` is required.
`import_name` Required	String	Handle used when importing the library in transformation code — must be camelCase of `name`. Validation fails if `import_name` does not match the camelCase form of `name`.

Library validation rules

Transformation library must be semantically valid

semantic error

Rule ID: transformations/transformation-library/semantic-valid

Examples

Transformation library with unique import_name

A single library whose import_name no other library claims validates cleanly.

spec.yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  id: math-utils
  name: Math Utils
  import_name: mathUtils
  language: javascript
  code: |
    export function round(value) {
      return Math.round(value);
    }

Duplicate transformation library import_name

Two libraries declaring the same import_name collide in the resource graph and fail validation.

spec.yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: math-utils
spec:
  id: math-utils
  name: Math Utils
  import_name: mathUtils
  language: javascript
  code: |
    export function round(value) {
      return Math.round(value);
    }

spec2.yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: math-helpers
spec:
  id: math-helpers
  name: Math Utils
  import_name: mathUtils
  language: javascript
  code: |
    export function ceil(value) {
      return Math.ceil(value);
    }

Diagnostics

spec.yaml /import_name import_name 'mathUtils' is duplicate
spec2.yaml /import_name import_name 'mathUtils' is duplicate

Transformation library spec syntax must be valid

syntactic error

Rule ID: transformations/transformation-library/spec-syntax-valid

Examples

Valid transformation library spec with inline JavaScript

spec.yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  id: math-utils
  name: Math Utils
  import_name: mathUtils
  description: Utility functions for math operations
  language: javascript
  code: |
    export function round(value) {
      return Math.round(value);
    }

Transformation library spec missing required id

spec.yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  name: Math Utils
  import_name: mathUtils
  language: javascript
  code: |
    export function round(value) {
      return Math.round(value);
    }

Diagnostics

spec.yaml /id 'id' is required

Transformation library spec missing required import_name

spec.yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  id: math-utils
  name: Math Utils
  language: javascript
  code: |
    export function round(value) {
      return Math.round(value);
    }

Diagnostics

spec.yaml /import_name 'import_name' is required

Transformation library import_name is not camelCase of name

spec.yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  id: math-utils
  name: Math Utils
  import_name: MathUtils
  language: javascript
  code: |
    export function round(value) {
      return Math.round(value);
    }

Diagnostics

spec.yaml /import_name 'import_name' must be camelCase of 'name'

Transformation library spec with unsupported language

spec.yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  id: math-utils
  name: Math Utils
  import_name: mathUtils
  language: ruby
  code: |
    def round(value)
      value.round
    end

Diagnostics

spec.yaml /language 'language' must be one of [javascript python]

Testing framework

Rudder CLI includes a rich built-in testing framework for validating transformations and transformation libraries locally.

Structure

The testing framework uses input and output directories to run test cases:

All files in the input directory are treated as test inputs
Corresponding files in the output directory are used as expected outputs for comparison against the actual transformation results

Input and output file names must match for accurate testing and comparison.

For each test case, the framework sends the input event through the transformation and compares the actual output against the expected output.

Test modes

The testing framework supports two modes:

Mode	Description
Default	Displays minimal details about test results.
`--verbose`	Displays more context around differences, including three lines above and below each code diff.

Test result classification

Each input file represents a separate test case. Rudder CLI classifies transformation test results into the following categories:

Result	Description
Passed	The actual output matches the expected output. If the expected output is missing, then a successful execution is considered as passed.
Execution error	The transformation code encountered an error during execution.
Output mismatch error	The actual output doesn’t match the expected output.

Transformation library tests focus specifically on syntax validation.

See more

See Manage Transformations Using Rudder CLI for feature overview
See Transformations Quickstart for a complete end-to-end example

Transformation YAML Reference Beta

Overview

Transformation resource

spec properties

tests properties

Validation rules

Transformation imports must resolve to existing transformation libraries

Examples

Transformation without library imports is valid

Transformation imports a missing library

Transformation spec syntax must be valid

Examples

Valid transformation spec with inline JavaScript

Transformation spec missing required id

Transformation spec missing the required language

Transformation spec defined with an unsupported language

Transformation spec missing code and file

Transformation library resource

spec properties

Library validation rules

Transformation library must be semantically valid

Examples

Transformation library with unique import_name

Duplicate transformation library import_name

Transformation library spec syntax must be valid

Examples

Valid transformation library spec with inline JavaScript

Transformation library spec missing required id

Transformation library spec missing required import_name

Transformation library import_name is not camelCase of name

Transformation library spec with unsupported language

Testing framework

Structure

Test modes

Test result classification

See more

Questions? We're here to help.

`spec` properties

`tests` properties

`spec` properties