Spec Version: v1 (Latest)v0.1

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

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:

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.

version: rudder/v1

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.

version: rudder/v1
kind: tracking-plan

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:

The following example shows an event referencing a category:

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

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

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

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

config keys converted to snake case

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

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.

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

- id: status_code
  type: "integer,null"

Array item types hoisted to top-level

- id: tag_list
  type: array
  item_type: string

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

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

Full property definition example

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

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

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

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

Config keys converted from camel to snake case

config:
  min_length: 10
  max_length: 255

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)

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

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

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

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

Full Tracking Plan example

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

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

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

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.

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

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

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

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.

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

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"