Select spec version:

Transformation YAML Reference Beta

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

Available Plans

free
growth
enterprise

13 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

URNs must be unique across the project

syntactic error

Rule ID: project/duplicate-urn

Examples

Distinct URNs across files

Each spec declares a different resource, so URNs do not collide.

a.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed

b.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: cart_viewed
      name: Cart Viewed

Same URN declared in two files

Both files declare the same event ID, which resolves to one URN. The rule flags each occurrence.

a.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed

b.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: order_completed
      name: Order Completed (duplicate)

Diagnostics

a.yaml /spec/events/0/id duplicate URN 'event:order_completed'
b.yaml /spec/events/0/id duplicate URN 'event:order_completed'

A (workspace_id, urn) must not be defined in both an import-manifest and inline metadata.import with differing remote_ids

syntactic error

Rule ID: project/manifest-inline-conflict

Examples

Manifest and inline metadata import distinct resources

One resource is imported via the manifest, a different one via inline metadata. No URN appears in both, so the project is valid.

events.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:cart_viewed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
    - id: cart_viewed
      name: Cart Viewed

import-manifest.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Same URN imported by both a manifest and inline metadata

The URN event:order_completed is declared in both the manifest and an inline metadata.import block — an ambiguous double import. The rule flags both locations; remove one.

events.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:order_completed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed

import-manifest.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Diagnostics

import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

The events spec uses the legacy rudder/0.1 format, whose inline imports reference resources by local_id + remote_id. The local_id order_completed resolves to the URN event:order_completed — the same URN the manifest imports. Legacy specs are still subject to the conflict rule, so both locations are flagged; remove the inline metadata entry.

events.yaml yaml

version: rudder/0.1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - local_id: order_completed
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed

import-manifest.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Diagnostics

import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Metadata syntax must be valid

syntactic error

Rule ID: project/metadata-syntax-valid

Examples

Metadata with only the required name

Minimal valid metadata: a name only.

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events: []

Metadata with a well-formed import block

An import block where each workspace declares workspace_id and each resource references a URN in the spec body.

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - workspace_id: ws-123
        resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed

Metadata missing required name

Every spec metadata block must declare a name.

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  import:
    workspaces:
      - workspace_id: ws-123
spec:
  events: []

Diagnostics

spec.yaml /metadata/name 'name' is required

Import workspace missing required workspace_id

Each import workspace entry must declare a workspace_id.

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed

Diagnostics

spec.yaml /metadata/import/workspaces/0/workspace_id 'workspace_id' is required

Transformation imports must resolve to existing transformation libraries

semantic error

Rule ID: transformations/transformation/semantic-valid

Examples

Transformation without library imports is valid

spec.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - 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

spec.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - 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 yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - 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 yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - 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 yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - 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 yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - 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 yaml

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

Diagnostics

spec.yaml /code 'code' is required when 'file' 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

URNs must be unique across the project

syntactic error

Rule ID: project/duplicate-urn

Examples

Distinct URNs across files

Each spec declares a different resource, so URNs do not collide.

a.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed

b.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: cart_viewed
      name: Cart Viewed

Same URN declared in two files

Both files declare the same event ID, which resolves to one URN. The rule flags each occurrence.

a.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed

b.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: order_completed
      name: Order Completed (duplicate)

Diagnostics

a.yaml /spec/events/0/id duplicate URN 'event:order_completed'
b.yaml /spec/events/0/id duplicate URN 'event:order_completed'

A (workspace_id, urn) must not be defined in both an import-manifest and inline metadata.import with differing remote_ids

syntactic error

Rule ID: project/manifest-inline-conflict

Examples

Manifest and inline metadata import distinct resources

One resource is imported via the manifest, a different one via inline metadata. No URN appears in both, so the project is valid.

events.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:cart_viewed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
    - id: cart_viewed
      name: Cart Viewed

import-manifest.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Same URN imported by both a manifest and inline metadata

The URN event:order_completed is declared in both the manifest and an inline metadata.import block — an ambiguous double import. The rule flags both locations; remove one.

events.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:order_completed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed

import-manifest.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Diagnostics

import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

events.yaml yaml

version: rudder/0.1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - local_id: order_completed
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed

import-manifest.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Diagnostics

import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Metadata syntax must be valid

syntactic error

Rule ID: project/metadata-syntax-valid

Examples

Metadata with only the required name

Minimal valid metadata: a name only.

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events: []

Metadata with a well-formed import block

An import block where each workspace declares workspace_id and each resource references a URN in the spec body.

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - workspace_id: ws-123
        resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed

Metadata missing required name

Every spec metadata block must declare a name.

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  import:
    workspaces:
      - workspace_id: ws-123
spec:
  events: []

Diagnostics

spec.yaml /metadata/name 'name' is required

Import workspace missing required workspace_id

Each import workspace entry must declare a workspace_id.

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed

Diagnostics

spec.yaml /metadata/import/workspaces/0/workspace_id 'workspace_id' is required

Transformation library must be semantically valid

semantic error

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

Examples

Transformation library with unique import_name

spec.yaml yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - 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

spec.yaml yaml

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

Diagnostics

spec.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 yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - 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 yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - 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 yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - 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 yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - 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 yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - 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

URNs must be unique across the project

Examples

Distinct URNs across files

Same URN declared in two files

A (workspace_id, urn) must not be defined in both an import-manifest and inline metadata.import with differing remote_ids

Examples

Manifest and inline metadata import distinct resources

Same URN imported by both a manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

Metadata syntax must be valid

Examples

Metadata with only the required name

Metadata with a well-formed import block

Metadata missing required name

Import workspace missing required workspace_id

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

URNs must be unique across the project

Examples

Distinct URNs across files

Same URN declared in two files

A (workspace_id, urn) must not be defined in both an import-manifest and inline metadata.import with differing remote_ids

Examples

Manifest and inline metadata import distinct resources

Same URN imported by both a manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

Metadata syntax must be valid

Examples

Metadata with only the required name

Metadata with a well-formed import block

Metadata missing required name

Import workspace missing required workspace_id

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? Let's figure it out together.

`spec` properties

`tests` properties

`spec` properties