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

PropertyType
Description
id
Required		StringUnique project ID for the transformation.
name
Required		StringHuman-readable name. Must be non-empty.
language
Required		StringTransformation language. Allowed values: javascript, python.
descriptionStringOptional description.
codeStringInline transformation code containing valid syntax for the selected language. Mutually exclusive with file.
fileStringPath 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.
warning
One of code or file is required.
testsArrayOptional 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

PropertyType
Description
name
Required		StringTest suite name. Must be non-empty and can contain only letters, numbers, spaces, _, -, and /.
inputStringDirectory with JSON input payload files. Relative paths resolve from the spec directory. If omitted, default is ./input.
outputStringDirectory with expected output JSON files. Relative paths resolve from the spec directory. If omitted, default is ./output.
info

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

Spec version
Filter by phase

Showing 2 of 2 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

PropertyType
Description
id
Required		StringUnique project ID for the library.
name
Required		StringHuman-readable name — must be non-empty.
descriptionStringOptional description.
language
Required		StringLibrary language. Allowed values are javascript and python.
codeStringInline library code containing valid syntax for the selected language. Mutually exclusive with file.
fileStringPath 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.
warning
One of code or file is required.
import_name
Required		StringHandle used when importing the library in transformation code — must be camelCase of name.

warning
Validation fails if import_name does not match the camelCase form of name.

Library validation rules

Spec version
Filter by phase

Showing 2 of 2 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
warning
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:

ModeDescription
DefaultDisplays minimal details about test results.
--verboseDisplays 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:

ResultDescription
PassedThe actual output matches the expected output. If the expected output is missing, then a successful execution is considered as passed.
Execution errorThe transformation code encountered an error during execution.
Output mismatch errorThe actual output doesn’t match the expected output.
info
Transformation library tests focus specifically on syntax validation.

See more

Questions? We're here to help.

Join the RudderStack Slack community or email us for support

Slack Join now → Email Reach out →