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

❗

Important: There must be a space after the colon.

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.

Dashboard

YAML