Dify DSL explained: importing YAML templates without breaking your workspace

Dify's DSL import is one of its best features and its quietest footgun. A YAML file that "imports fine" can still fail at runtime, leak intent you didn't review, or silently bind to the wrong model provider. A field guide.

Anatomy of a DSL file

version: "0.7.0"        # schema generation (1.16.x → 0.7.x)
kind: app
app:
  mode: workflow         # workflow | advanced-chat | chat | agent
workflow:
  graph:
    nodes: [...]         # id / data.type / position
    edges: [...]         # source/target + handles + type metadata

The five checks before importing anything

1. Version match. 0.7.0 targets Dify 1.16+; older files warn or break on newer cores. Check the top two lines first.
2. Graph integrity. Every edge's source/target must reference existing node IDs. IF/ELSE branches use custom source handles (true/false/label) — normal edges use source.
3. Variable references. Prompts embed variables as {{#node_id.field#}}. Typos survive visual inspection and detonate at runtime. System vars start with sys. — those aren't node references.
4. Prompt review. You are importing instructions that will run with YOUR credentials. Read every system prompt for injected behavior — especially in templates from strangers.
5. Dependencies. Marketplace plugins are pinned by identifier hash. If your workspace lacks the plugin, imports warn — resolve them in the plugins panel before running.

Common runtime failures that pass import

• Provider mismatch: template says langgenius/openai/openai, your workspace configured a different path → configure credentials for the exact referenced provider.
• Model name drift: gpt-4o-mini vs gpt-4.1-mini-era templates — swap model names in LLM nodes to what your account offers.
• Omitted assets in agent apps: portable agent packages deliberately exclude secrets/contacts/skills — reconnect after import per the warnings panel.

Treat DSL like infrastructure code

Export before upgrades, commit YAML to git, diff reviews for prompt changes. Teams that do this iterate ten times faster than canvas-clickers, and roll back instantly when a prompt edit goes sideways.