# Transformation YAML Reference > Complete YAML reference for transformation and transformation-library resources managed with Rudder CLI. 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:

**Warning:** 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`](https://www.rudderstack.com/docs/rudder-cli/transformations-walkthrough/#6-test-transformations-locally) and are not synced to workspace state during [`rudder-cli apply`](https://www.rudderstack.com/docs/rudder-cli/transformations-walkthrough/#7-apply-changes). | ### `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`. | **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 5 of 5 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:

**Warning:** 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`.

**Warning:** Validation fails if `import_name` does not match the camelCase form of `name`. | ### Library validation rules
Spec version
Filter by phase

Showing 5 of 5 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 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 **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: | 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. | **Info:** Transformation library tests focus specifically on syntax validation. ## See more - See [Manage Transformations Using Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/manage-transformations/) for feature overview - See [Transformations Quickstart](https://www.rudderstack.com/docs/rudder-cli/transformations-walkthrough/) for a complete end-to-end example