Deep Merging

When the orchestrator successfully intercepts a file (either via Templates or Config Injection), and that file already exists in the runtime container, it intelligently deep-merges them based on the extension!

Each payload also supports Variable Interpolation using the $[VARIABLE_NAME] syntax. This occurs before any merging logic hits the file!

It actively supports preserving comments across most formats (YAML, TOML, and Properties)! You can also use key-level sigils (!replace: and !delete:) directly within these structured configuration files to bypass standard merging logic on specific dictionaries.

YAML (.yml, .yaml)

Because the orchestrator relies on ruamel.yaml, your structural comments remain entirely untouched.

In this example, we change the port via standard merging, !delete: the legacy rules completely, and !replace: the entire advanced dictionary (wiping out old properties that aren't explicitly inside the new template block).

# server config
server:
  port: 25565
  # Should we enable online mode?
  online-mode: true
  legacy_rules: true
  advanced:
    cache: true
    debug: false

server:
  port: 25566
  '!delete:legacy_rules': ''
  '!replace:advanced':
    cache: false

Result (in Runtime)

# server config
server:
  port: 25565
  port: 25566
  # Should we enable online mode?
  online-mode: true
  legacy_rules: true
  advanced: 
    cache: true
    debug: false
  advanced: 
    cache: false

JSON (.json)

JSON supports the exact same nested behavior. Here we !replace the features dict completely and !delete a deprecated key, while seamlessly deep merging new_system.

{
  "max_players": 20,
  "features": {
    "flight": false,
    "rcon": false
  },
  "old_system": true,
  "new_system": false
}

{
  "!replace:features": {
    "rcon": true
  },
  "!delete:old_system": null,
  "new_system": true
}

Result (in Runtime)

{
  "max_players": 20,
  "features": {
    "flight": false, 
    "rcon": false, 
    "rcon": true
  },
  "old_system": true, 
  "new_system": false, 
  "new_system": true
}

TOML (.toml)

TOML supports sigils on both flat keys and table structures. Below we change the debug flag naturally, !delete: the legacy flag, and !replace: the entire database table layout.

# Main settings
[core]
debug = false # Change to true to log everything
legacy = true

[database]
uri = "localhost:5432"
timeout = 30

[core]
debug = true
"!delete:legacy" = true

["!replace:database"]
uri = "remote:5432"

Result (in Runtime)

# Main settings
[core]
debug = false # Change to true to log everything 
debug = true  # Change to true to log everything 
legacy = true

[database] 
uri = "localhost:5432"
timeout = 30

[database] 
uri = "remote:5432"

Java Properties (.properties)

Because Java Properties are essentially flat lists without objects or arrays, !replace: is completely unnecessary - overriding properties defaults to 1:1 replacement anyway! However, !delete: remains invaluable to remove stale flags perfectly.

# Minecraft server properties
view-distance=10
enable-command-block=false
legacy-mode=true
motd=A Minecraft Server

view-distance=12
!delete:legacy-mode=true
motd=mc-orchestrator rules!

Result (in Runtime)

# Minecraft server properties
view-distance=10            
view-distance=12            
enable-command-block=false
legacy-mode=true            
motd=A Minecraft Server     
motd=mc-orchestrator rules! 

HOCON (.conf)

HOCON (Human-Optimized Config Object Notation) is a super-set of JSON often found in plugins like LuckPerms or Sponge. The orchestrator allows deep-merging .conf files exactly like JSON.

storage-method = "h2"
data {
  address = "127.0.0.1"
  pool-settings {
    maximum-pool-size = 10
  }
}

storage-method = "postgresql"
data {
  address = "192.168.1.100"
  "!replace:pool-settings" {
    max = 20
  }
}

Result (in Runtime)

storage-method = "h2"
storage-method = "postgresql"
data {
  address = "127.0.0.1"
  address = "192.168.1.100"
  pool-settings {
    maximum-pool-size = 10
    max = 20
  }
}