What are the differences between YAML 1.1 and YAML 1.2? How to handle version compatibility issues?

YAML 1.1 and YAML 1.2 are the two main versions of YAML, and there are important differences between them. Understanding these differences is crucial for using YAML correctly.

Version History

YAML 1.1

• Released in 2005
• Widely adopted, default version for many tools and libraries
• Good compatibility with JSON

YAML 1.2

• Released in 2009
• Aims for complete JSON compatibility
• Simplified syntax rules, improved predictability
• Resolved some ambiguity issues in YAML 1.1

Key Differences

1. Type Inference Rules

YAML 1.1

yaml
# YAML 1.1 infers these values as specific types
yes: yes              # Boolean true
no: no                # Boolean false
on: on                # Boolean true
off: off              # Boolean false
123_456: 123_456      # Number 123456
0b1010: 0b1010        # Binary number 10
0o755: 0o755          # Octal number 493
0x1F: 0x1F            # Hexadecimal number 31

YAML 1.2

yaml
# YAML 1.2 has stricter type inference
yes: "yes"            # Needs quotes to be string
no: "no"              # Needs quotes to be string
on: "on"              # Needs quotes to be string
off: "off"            # Needs quotes to be string
123_456: 123_456      # Number 123456 (retained)
0b1010: 0b1010        # Binary number 10 (retained)
0o755: 0o755          # Octal number 493 (retained)
0x1F: 0x1F            # Hexadecimal number 31 (retained)

2. Boolean Representation

YAML 1.1

Supports more boolean representations:

• true, false
• yes, no
• on, off

YAML 1.2

Only supports:

• true, false
• Other values need explicit type specification or quotes

3. Octal Notation

YAML 1.1

yaml
# Numbers starting with 0 are interpreted as octal
port: 0808  # Octal, equals decimal 520

YAML 1.2

yaml
# Numbers starting with 0 are interpreted as decimal
port: 0808  # Decimal 808 (if parser supports)
# Or use explicit octal notation
port: 0o755  # Octal 493

4. Tag Parsing

YAML 1.1

yaml
# !! tags used for type conversion
value: !!str 123  # String "123"
date: !!timestamp 2024-01-01

YAML 1.2

yaml
# Tag system more standardized
value: !!str 123  # String "123"
date: !!timestamp 2024-01-01
# New standard tags added
binary: !!binary SGVsbG8=

5. Escape Characters

YAML 1.1

yaml
# Supports more escape characters
text: "\x41"  # Hexadecimal character
text: "\u0041"  # Unicode character

YAML 1.2

yaml
# Escape characters more standardized
text: "\x41"  # Hexadecimal character
text: "\u0041"  # Unicode character
text: "\U00000041"  # Extended Unicode

6. Flow Style

YAML 1.1

yaml
# Collections in flow style
list: [a, b, c]
map: {key: value, key2: value2}

YAML 1.2

yaml
# Flow style more flexible
list: [a, b, c]
map: {key: value, key2: value2}
# Supports nested flow style
nested: [a, [b, c], {key: value}]

Compatibility Issues

Backward Compatibility

YAML 1.2 aims to maintain backward compatibility with YAML 1.1, but there are exceptions:

yaml
# In YAML 1.1, yes is boolean true
enabled: yes

# In YAML 1.2, yes might be interpreted as string
# Need to use quotes or explicit type
enabled: "yes"
enabled: !!bool yes

JSON Compatibility

YAML 1.2 has better JSON compatibility:

yaml
# Valid JSON is also valid YAML 1.2
{
  "name": "John",
  "age": 30,
  "active": true
}

Practical Impact

1. Configuration File Parsing

yaml
# May have different interpretations in different versions
mode: 0755  # YAML 1.1: Octal 493, YAML 1.2: Decimal 755

2. Boolean Configuration

yaml
# May cause unexpected type conversion
debug: yes  # YAML 1.1: true, YAML 1.2: possibly string

3. Number Format

yaml
# Number formats may have different interpretations in different versions
port: 0808  # YAML 1.1: 520 (octal), YAML 1.2: 808 (decimal)

Version Detection

Specify Version in Document

yaml
%YAML 1.2
---
# YAML 1.2 content

Specify Version in Code

Python (PyYAML):

python
import yaml

# Default uses YAML 1.1
data = yaml.safe_load(open('config.yaml'))

# Use YAML 1.2 (requires ruamel.yaml)
from ruamel.yaml import YAML
yaml = YAML(typ='safe', version=(1, 2))
data = yaml.load(open('config.yaml'))

JavaScript (js-yaml):

javascript
const yaml = require('js-yaml');

// Default supports YAML 1.2
const data = yaml.safeLoad(fs.readFileSync('config.yaml', 'utf8'));

Best Practices

1. Explicitly Specify Version: Declare version at the beginning of YAML file
2. Use Quotes: For potentially ambiguous values, use quotes to explicitly specify as string
3. Test Compatibility: Ensure configuration behaves consistently across different parsers
4. Document: Record YAML version used and special configurations
5. Validation Tools: Use YAML linter to validate configuration files

Migration Guide

Migrating from YAML 1.1 to 1.2

1. Check Booleans:

   yaml
   # YAML 1.1
   enabled: yes
   
   # YAML 1.2
   enabled: true
   # or
   enabled: "yes"

2. Check Octal Numbers:

   yaml
   # YAML 1.1
   mode: 0755
   
   # YAML 1.2
   mode: 0o755

3. Check Type Inference:

   yaml
   # YAML 1.1
   value: on
   
   # YAML 1.2
   value: true
   # or
   value: "on"

Tool Support

YAML 1.1 Parsers

• PyYAML (Python)
• SnakeYAML (Java)
• LibYAML (C)

YAML 1.2 Parsers

• ruamel.yaml (Python)
• js-yaml (JavaScript)
• yaml-cpp (C++)

Choosing the appropriate parser version is important for ensuring correct configuration parsing.