Overview

Use the pup idp migrate-schema command to migrate your existing service YAML files from v1, v2, v2.1, or v2.2 to the v3 entity format. The command handles field remapping, link type normalization, companion entity generation, and output validation against the official v3 JSON schemas before writing to disk.

Prerequisites

Install pup:

brew tap datadog-labs/pack
brew install pup

Note: If pup is already installed, run brew upgrade pup to use the latest version.

Migrated fields

The following fields are remapped from v1, v2, v2.1, or v2.2 to their v3 destinations:

Link types are also normalized: wiki → doc, code → repo, url and oncall → other.

Migrate a single file

Run the command with the path to a single YAML file:

pup idp migrate-schema service.datadog.yaml

The command detects the schema version, migrates the file, validates the output against the official v3 schemas, then prompts you for where to write the result:

Where would you like to write the output?
  [1] Write to ./entity.datadog.yaml (same directory, delete original)
  [2] Specify a custom path
  [3] Print to stdout only
>

• Option 1 writes the migrated content to entity.datadog.yaml in the same directory and deletes the original file.
• Option 2 prompts for a path and writes there.
• Option 3 prints the migrated YAML to stdout, useful for reviewing or piping without writing.

If the migrated output fails validation, you are prompted to abort or write anyway:

✗ INVALID  [service] payment-service
    [spec/tier] "Tier1" is not valid under any of the given schemas
[1] Abort  [2] Write anyway >

Migrate all files in a directory

Pass a directory path to recursively discover and migrate all *.datadog.yaml files:

pup idp migrate-schema ./catalog/

If multiple files are found, the command lists them and asks whether to migrate one or all:

Found 4 catalog files:
  [1] catalog/checkout-api.datadog.yaml
  [2] catalog/payment-service.datadog.yaml
  [3] catalog/inventory-service.datadog.yaml
  [4] catalog/auth-service.datadog.yaml
Enter number to migrate one, or "all" to migrate all:

When migrating all files, the command asks for a single confirmation, then migrates all files in parallel. The command prints a summary:

Migrated 4 files • 6 services • 2 systems • 0 invalid • 1.2s

Autodiscover from the current directory

If no path is given, pup searches the current working directory recursively:

cd ~/my-repo
pup idp migrate-schema

Companion system entities

If your v1 or v2 definitions include an application: field, the command generates a companion kind: system entity and appends the companion entity to the output file. Duplicate system names across a multi-document file are deduplicated into a single entity.

Input (v2):

schema-version: v2
dd-service: payment-service
team: payments-team
application: checkout-platform

Output (v3):

---
apiVersion: v3
kind: service
metadata:
  name: payment-service
  owner: payments-team
spec:
  componentOf:
    - system:checkout-platform
---
apiVersion: v3
kind: system
metadata:
  name: checkout-platform
  owner: payments-team
spec:
  components:
    - service:payment-service

Validation

After migration, the tool fetches the official v3 JSON schemas from the public DataDog/schema GitHub repository and validates each entity. Results are printed inline:

✓ VALID    [service] payment-service
✓ VALID    [system] checkout-platform
✗ INVALID  [service] inventory-service
    [spec/lifecycle] "depreciated" is not one of ["experimental","active","deprecated","end-of-life"]

Validation failures are warnings — they do not block you from writing the output, but should be resolved before merging the definition into your repository.

Further reading

Additional helpful documentation, links, and articles:

Learn about the v3 entity modelDOCUMENTATION Learn about native entity typesDOCUMENTATION Create custom entity typesDOCUMENTATION pup idp migrate-schema sourceSOURCE CODE