Select spec version:

How to Migrate from Rudder CLI Spec v0.1 to v1 Beta

Migrate your Rudder CLI project from spec format v0.1 to v1 with an automated command.

Available Plans

free
growth
enterprise

7 minute read

This migration guide helps you migrate your Rudder CLI project from spec version 0.1 to v1.

Overview

rudder/v1 is a comprehensive redesign of the original rudder/v0.1 spec format. It improves consistency across resource kinds, replaces ambiguous field names, adopts snake case conventions, and moves to compact URN-style references throughout.

When you run the migrate command, Rudder CLI automatically rewrites the spec files present in the specified location and applies changes related to:

Spec version upgrades
Rename resource kinds
Using compact URN references
Updating property and custom type definitions
Updating Tracking Plan rules
Updating variant definitions
Updating import metadata
Updating event stream source references

As the migration process rewrites the spec files in place, RudderStack recommends committing or backing up your project before running the migrate command.

Run the migration

To migrate your project automatically, run the following command:

bash

rudder-cli migrate --location <path-to-project>

Breaking changes

The following sections list the breaking changes introduced in the spec format upgrade from v0.1 to v1.

The migrate command automatically handles these changes.

Update the version field

The field-name, convention, and reference changes in rudder/v1 break the existing spec contract. The version is bumped to signal the new contract, so tooling and validation can distinguish it from legacy spec version rudder/v0.1.

yaml

version: rudder/v1

yaml

version: rudder/0.1
# or
version: rudder/v0.1

Rename the Tracking Plan kind

The Tracking Plan kind changes from tp to tracking-plan. The abbreviated tp was an opaque abbreviation, while tracking-plan is self-documenting and consistent with how the resource is named everywhere else.

yaml

version: rudder/v1
kind: tracking-plan

yaml

version: rudder/v0.1
kind: tp

Compact URN references

All cross-resource references change from the path-based format (#/<kind>/<group>/<id>) to the compact URN format (#<resource-type>:<id>). Path-based references were verbose and order-dependent, while compact URNs are shorter and encode the resource type, making references unambiguous and easier to read.

The following table lists the updated reference format for each resource type:

Resource	v0.1	v1
Property	`#/properties/group/prop_id`	`#property:prop_id`
Event	`#/events/group/event_id`	`#event:event_id`
Category	`#/categories/group/cat_id`	`#category:cat_id`
Custom type	`#/custom-types/group/type_id`	`#custom-type:type_id`
Tracking plan	`#/tp/group/tp_id`	`#tracking-plan:tp_id`

The following example shows an event referencing a category:

yaml

version: rudder/v1
kind: events
spec:
  events:
    - id: api_tracking
      name: API Tracking
      event_type: track
      category: "#category:user_actions"

yaml

version: rudder/v0.1
kind: events
spec:
  events:
    - id: api_tracking
      name: API Tracking
      event_type: track
      category: "#/categories/app_categories/user_actions"

Updated property definitions

Property definitions undergo four changes:

propConfig is renamed to config for brevity and consistency with other resource field naming
config keys move to snake case to align with YAML ecosystem conventions
type becomes types (an array) to eliminate fragile comma-separated string parsing
Array item types are hoisted to top-level to reduce nesting and make type information more discoverable

`propConfig` renamed to `config`

yaml

config:
  enum: ["GET", "PUT", "POST"]

yaml

propConfig:
  enum: ["GET", "PUT", "POST"]

`config` keys converted to snake case

yaml

config:
  minimum: 0
  maximum: 10
  multiple_of: 2
  min_length: 10
  max_length: 64

yaml

propConfig:
  minimum: 0
  maximum: 10
  multipleOf: 2
  minLength: 10
  maxLength: 64

Multi-type `type` string replaced by `types` array

Properties with multiple types use a types array instead of a comma-separated type string.

yaml

- id: status_code
  types:
    - integer
    - "null"

yaml

- id: status_code
  type: "integer,null"

Array item types hoisted to top-level

yaml

- id: tag_list
  type: array
  item_type: string

# Multiple item types
- id: user_scores
  type: array
  item_types:
    - integer
    - number

yaml

- id: tag_list
  type: array
  propConfig:
    itemTypes:
      - string

Full property definition example

yaml

version: rudder/v1
kind: properties
metadata:
  name: api_tracking
spec:
  properties:
    - id: api_method
      name: API Method
      type: string
      description: "http method of the api called"
      config:
        enum: ["GET", "PUT", "POST", "DELETE", "PATCH"]
    - id: http_retry_count
      name: HTTP Retry Count
      type: integer
      description: "Number of times to retry the API call"
      config:
        minimum: 0
        maximum: 10
        multiple_of: 2
    - id: password
      name: Password
      type: string
      config:
        min_length: 10
        max_length: 64

yaml

version: rudder/v0.1
kind: properties
metadata:
  name: api_tracking
spec:
  properties:
    - id: api_method
      name: API Method
      type: string
      description: "http method of the api called"
      propConfig:
        enum: ["GET", "PUT", "POST", "DELETE", "PATCH"]
    - id: http_retry_count
      name: HTTP Retry Count
      type: integer
      description: "Number of times to retry the API call"
      propConfig:
        minimum: 0
        maximum: 10
        multipleOf: 2
    - id: password
      name: Password
      type: string
      propConfig:
        minLength: 10
        maxLength: 64

Custom type definitions

Custom type definitions undergo two changes:

$ref (a JSON Schema artifact with no semantic meaning in this context) is replaced by the clearer property
config keys follow the same snake case convention as properties

`$ref` replaced by `property` in type properties

yaml

spec:
  types:
    - id: login
      type: object
      properties:
        - property: "#property:username"
          required: true

yaml

spec:
  types:
    - id: login
      type: object
      properties:
        - $ref: "#/properties/api_tracking/username"
          required: true

Config keys converted from camel to snake case

yaml

config:
  min_length: 10
  max_length: 255

yaml

config:
  minLength: 10
  maxLength: 255

Tracking Plan rules

Tracking Plan rules undergo two structural changes:

The event object wrapper was redundant, so event now holds a direct reference string consistent with how other references are expressed.
allow_unplanned is renamed to additional_properties and moved to rule level for clarity.
$ref is replaced by property in rule properties, using compact URNs

The `event` object replaced with a direct reference string

The event field changes from an object (containing $ref, allow_unplanned, and identity_section) to a direct reference string. The allow_unplanned and identity_section fields move to rule level:

event.$ref becomes event (direct string)
event.allow_unplanned becomes additional_properties (moved to rule level and renamed)
event.identity_section becomes identity_section (moved to rule level)

yaml

rules:
  - type: event_rule
    id: login
    event: "#event:api_tracking"
    additional_properties: false
    identity_section: properties

yaml

rules:
  - type: event_rule
    id: login
    event:
      $ref: "#/events/api_tracking/api_tracking"
      allow_unplanned: false
      identity_section: properties

`$ref` replaced by `property` in rule properties

yaml

properties:
  - property: "#property:username"
    required: true
  - property: "#property:password"
    required: true

yaml

properties:
  - $ref: "#/properties/api_tracking/username"
    required: true
  - $ref: "#/properties/api_tracking/password"
    required: true

Full Tracking Plan example

yaml

version: rudder/v1
kind: tracking-plan
metadata:
  name: api_tracking
spec:
  id: api_tracking
  display_name: API Tracking
  rules:
    - type: event_rule
      id: login
      event: "#event:api_tracking"
      additional_properties: false
      properties:
        - property: "#property:username"
          required: true
        - property: "#property:password"
          required: true

yaml

version: rudder/v0.1
kind: tp
metadata:
  name: api_tracking
spec:
  id: api_tracking
  display_name: API Tracking
  rules:
    - type: event_rule
      id: login
      event:
        $ref: "#/events/api_tracking/api_tracking"
        allow_unplanned: false
      properties:
        - $ref: "#/properties/api_tracking/username"
          required: true
        - $ref: "#/properties/api_tracking/password"
          required: true

Variant definitions

Variants appear in both custom types and Tracking Plan rules — they undergo the following changes:

The variant default is restructured to remove an array-of-objects pattern in favor of an explicit properties wrapper that matches the shape used in rules
All $ref fields within variant discriminators and cases are replaced by property with compact URN references

Variant `default` restructured from array to object

yaml

variants:
  - type: discriminator
    default:
      properties:
        - property: "#property:prop_a"
          required: true

yaml

variants:
  - type: discriminator
    default:
      - $ref: "#/properties/group/prop_a"
        required: true

Variant discriminator and case properties

Variant discriminator and case properties follow the same $ref to property change.

yaml

variants:
  - type: discriminator
    discriminator: "#property:api_method"
    cases:
      - display_name: "Create Entity"
        match: ["POST"]
        properties:
          - property: "#property:user_agent"
            required: true

yaml

variants:
  - type: discriminator
    discriminator: "#/properties/api_tracking/api_method"
    cases:
      - display_name: "Create Entity"
        match: ["POST"]
        properties:
          - $ref: "#/properties/api_tracking/user_agent"
            required: true

Import metadata

The local_id field in import metadata is replaced by a urn field that includes the resource type. The urn field encodes the resource type alongside the local ID, eliminating ambiguity when multiple resource types share the same ID values.

The URN format is <resource-type>:<local-id>.

Valid resource types include:

property
event
category
custom-type
tracking-plan
event-stream-source
retl-source-sql-model

yaml

metadata:
  name: test_props
  import:
    workspaces:
      - workspace_id: ws-123
        resources:
          - urn: property:prop1
            remote_id: remote-prop-1

yaml

metadata:
  name: test_props
  import:
    workspaces:
      - workspace_id: ws-123
        resources:
          - local_id: prop1
            remote_id: remote-prop-1

Event stream source references

The Tracking Plan reference in event stream source governance uses the compact URN format, consistent with the unified compact URN format adopted for all cross-resource references in v1.

yaml

version: rudder/v1
kind: event-stream-source
spec:
  id: test-source
  name: Test Source
  type: javascript
  governance:
    validations:
      tracking_plan: "#tracking-plan:tp-abc123"

yaml

version: rudder/v0.1
kind: event-stream-source
spec:
  id: test-source
  name: Test Source
  type: javascript
  governance:
    validations:
      tracking_plan: "#/tp/group/tp-abc123"

How to Migrate from Rudder CLI Spec v0.1 to v1 Beta

Overview

Run the migration

Breaking changes

Update the version field

Rename the Tracking Plan kind

Compact URN references

Updated property definitions

propConfig renamed to config

config keys converted to snake case

Multi-type type string replaced by types array

Array item types hoisted to top-level

Full property definition example

Custom type definitions

$ref replaced by property in type properties

Config keys converted from camel to snake case

Tracking Plan rules

The event object replaced with a direct reference string

$ref replaced by property in rule properties

Full Tracking Plan example

Variant definitions

Variant default restructured from array to object

Variant discriminator and case properties

Import metadata

Event stream source references

Questions? Let's figure it out together.

`propConfig` renamed to `config`

`config` keys converted to snake case

Multi-type `type` string replaced by `types` array

`$ref` replaced by `property` in type properties

The `event` object replaced with a direct reference string

`$ref` replaced by `property` in rule properties

Variant `default` restructured from array to object