YAML

YAML (YAML Ain't Markup Language) is the file format used by most Bukkit/Spigot/Paper plugins for configuration files, using indentation-based structure. Instead of complex XML tags or JSON brackets, YAML uses simple key-value pairs and indentation to create readable, hierarchical configuration files that server admins can easily understand and edit. Almost every plugin you install will have a config.yml file using this format.

What Is YAML?

YAML is a human-readable data serialization format which is a way to store structured data in plain text files. It's designed to be easy for humans to read and write while still being machine-parseable.​

A typical YAML configuration looks like this:

textserver-name: "My Minecraft Server"
max-players: 20
enable-pvp: true
spawn-location:
  world: world
  x: 0
  y: 64
  z: 0

YAML files use the .yml or .yaml file extension and are edited with any text editor.​

Key YAML Syntax Rules

Indentation Is Everything

YAML uses spaces (not tabs) for indentation to show hierarchy. Indented lines are nested inside lines one level higher:​

textpermissions:
  admin:
    - command.reload
    - command.op
  moderator:
    - command.kick
    - command.mute

Critical rules:

• Use 2 or 4 spaces per indentation level (2 is standard for Minecraft configs)​
• Never use tabs as they'll break your config file​
• Indentation must be consistent, mixing 2 and 4 spaces causes errors​

This is the most common source of YAML errors: incorrect indentation.​

Key-Value Pairs

The basic YAML structure is key: value:

textserver-port: 25565
motd: "Welcome to my server!"
online-mode: true

Lists/Arrays

Lists use hyphens followed by a space:

textworlds:
  - world
  - world_nether
  - world_the_end

Or inline format:

textworlds: [world, world_nether, world_the_end]

Strings and Quotes

Simple strings don't need quotes:

textmessage: Hello player

Use quotes for strings with special characters or to preserve spacing:

textmessage: "Hello: Player!"
colored-message: "&cRed Text"

Comments

Lines starting with # are comments and ignored by parsers:

# This is a comment
max-players: 20  # You can also comment at the end of lines

Common YAML Mistakes

Using Tabs Instead of Spaces

# WRONG - uses tabs
settings:
    max-players: 20  # Will cause parse errors
# CORRECT - uses spaces
settings:
  max-players: 20

Fix: Configure your text editor to insert spaces when you press Tab.​

Inconsistent Indentation

# WRONG - mixing 2 and 4 space indentation
permissions:
  admin:
      - command.op  # 4 spaces
  moderator:
    - command.kick  # 2 spaces
# CORRECT - consistent 2-space indentation
permissions:
  admin:
    - command.op
  moderator:
    - command.kick

Missing Space After Colon

# WRONG
max-players:20
# CORRECT
max-players: 20

Unquoted Special Characters

# WRONG - colon confuses parser
message: Hello: World

# CORRECT
message: "Hello: World"

Why Minecraft Uses YAML

Bukkit originally chose YAML for plugin configurations because:​

• Human-readable: Server admins can edit configs without programming knowledge​
• Less verbose than XML: No closing tags or excessive brackets​
• Built-in Bukkit support: The Bukkit API includes YAML parsing libraries​
• Hierarchical structure: Perfect for nested configuration options​

However, YAML has drawbacks. Meaningful whitespace and indentation rules confuse beginners, causing 10+ daily support requests in plugin communities.

Validating YAML Files

Before restarting your server with edited configs, validate your YAML syntax to catch errors:

• Use online validators like Online YAML Parser
• Install editor plugins like YAML Lint for VS Code
• Check server logs for YAML parse errors if your plugin fails to load​

Common error messages:

• while parsing a block mapping = indentation error​
• expected <block end>, but found = missing or extra indentation​
• could not find expected ':' = missing space after colon or syntax error​

Working with YAML in Plugins

Most plugins use Bukkit's built-in YAML parser through the FileConfiguration API:​

java// Loading a YAML file
FileConfiguration config = YamlConfiguration.loadConfiguration(file);

// Reading values
int maxPlayers = config.getInt("max-players");
String message = config.getString("welcome-message");

// Saving changes
config.set("max-players", 30);
config.save(file);

The plugin.yml file is a special YAML file required by all plugins that defines metadata like name, version, author, and commands.

Best Practices

• Use 2 spaces for indentation (Minecraft community standard)​
• Configure your editor with .editorconfig to automatically use spaces​
• Add comments to explain complex configuration sections​
• Validate before restarting to catch syntax errors early​
• Keep backups of working configs before making major changes​

YAML is the standard configuration format for Minecraft plugins because of its readability and simplicity. While its indentation-based syntax can trip up beginners, understanding the basic rules; use spaces not tabs, maintain consistent indentation, and add spaces after colons. This makes YAML configs easy to edit.