Convert Properties to TOML

Why Convert Properties to TOML?

Converting Java Properties files to TOML brings type safety and hierarchical structure to your configuration data. Properties files treat every value as a string, requiring manual parsing for integers, booleans, and other types. TOML natively supports strings, integers, floats, booleans, and date/time values, which means your configuration is validated at parse time rather than at runtime.

The dotted key convention used in Properties files (e.g., app.server.port=8080) maps naturally to TOML's table structure. Instead of repeating long prefixes on every line, TOML groups related settings under [app.server] table headers, making configuration files shorter, cleaner, and easier to navigate. This structural improvement is especially valuable for large configuration files with hundreds of properties.

TOML's growing adoption in modern toolchains makes it a forward-looking choice. Rust's Cargo, Python's pyproject.toml, Hugo's site configuration, and many other tools have chosen TOML as their primary configuration format. By converting your Properties files to TOML, you align with this modern trend and gain access to better tooling, validation, and editor support.

For teams migrating from Java-centric stacks to polyglot architectures, converting Properties to TOML provides a universal configuration format that works across languages. Unlike Properties files which are tightly coupled to the Java ecosystem, TOML has mature libraries in Python, Rust, Go, JavaScript, and virtually every modern programming language.

Key Benefits of Converting Properties to TOML:

• Type Safety: Native integer, float, boolean, and datetime types instead of all-string values
• Hierarchical Structure: Dotted keys become organized table sections
• Array Support: Native arrays replace comma-separated string values
• Clear Specification: TOML v1.0.0 eliminates parsing ambiguities
• Modern Ecosystem: Adopted by Rust, Python, Hugo, and growing community
• Better Readability: Grouped settings with explicit types are easier to understand
• Cross-Language Compatibility: Mature libraries available for all major languages

Practical Examples

Example 1: Spring Boot Application Configuration

Input Properties file (application.properties):

# Server configuration
server.port=8080
server.host=0.0.0.0
server.ssl.enabled=true
server.ssl.key-store=/etc/ssl/keystore.p12

# Database settings
spring.datasource.url=jdbc:postgresql://db:5432/myapp
spring.datasource.username=appuser
spring.datasource.pool.max-size=20
spring.datasource.pool.min-idle=5

Output TOML file (application.toml):

# Server configuration
[server]
port = 8080
host = "0.0.0.0"

[server.ssl]
enabled = true
key-store = "/etc/ssl/keystore.p12"

# Database settings
[spring.datasource]
url = "jdbc:postgresql://db:5432/myapp"
username = "appuser"

[spring.datasource.pool]
max-size = 20
min-idle = 5

Example 2: Logging Configuration

Input Properties file (logging.properties):

logging.level.root=INFO
logging.level.com.myapp=DEBUG
logging.level.org.springframework=WARN
logging.file.name=/var/log/myapp.log
logging.file.max-size=10485760
logging.file.max-history=30
logging.pattern.console=%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n

Output TOML file (logging.toml):

[logging.level]
root = "INFO"
"com.myapp" = "DEBUG"
"org.springframework" = "WARN"

[logging.file]
name = "/var/log/myapp.log"
max-size = 10485760
max-history = 30

[logging.pattern]
console = "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"

Example 3: Multi-Environment Feature Flags

Input Properties file (features.properties):

feature.dark-mode.enabled=true
feature.dark-mode.rollout-percent=75
feature.beta-api.enabled=false
feature.beta-api.allowed-users=admin,tester,devops
app.cache.ttl=3600
app.cache.max-entries=5000
app.retry.max-attempts=3
app.retry.delay-ms=1000

Output TOML file (features.toml):

[feature.dark-mode]
enabled = true
rollout-percent = 75

[feature.beta-api]
enabled = false
allowed-users = ["admin", "tester", "devops"]

[app.cache]
ttl = 3600
max-entries = 5000

[app.retry]
max-attempts = 3
delay-ms = 1000

Frequently Asked Questions (FAQ)

Q: What is a Java Properties file?

A: A Java Properties file (.properties) is a simple text-based configuration format from the Java ecosystem. Each line contains a key-value pair separated by = or :, with optional comments using # or !. It is the default configuration format for Java applications, Spring Boot, and many Apache projects.

Q: How are dotted property keys converted to TOML tables?

A: Dotted keys like app.server.port=8080 are decomposed into nested TOML table headers. The converter groups properties sharing the same prefix under a common table section such as [app.server], with the final key segment becoming the value name: port = 8080.

Q: Does the conversion preserve comments from Properties files?

A: Yes, comments prefixed with # in Properties files are carried over to the TOML output as # comments. Since TOML also uses # for comments, the mapping is straightforward. Comments using the ! prefix (a Properties-only convention) are converted to # syntax in TOML.

Q: How are data types handled during conversion?

A: Properties files store all values as strings. The converter intelligently detects types: numeric values become TOML integers or floats, "true"/"false" become booleans, and remaining values become quoted TOML strings. This type inference adds validation that raw Properties files lack.

Q: Can TOML handle Properties files with comma-separated lists?

A: Yes. Comma-separated values commonly used in Properties files (e.g., allowed.hosts=host1,host2,host3) can be converted to native TOML arrays: allowed-hosts = ["host1", "host2", "host3"]. This provides proper array semantics instead of requiring manual string splitting.

Q: Is TOML compatible with Spring Boot?

A: Spring Boot does not natively read TOML files, but the structured TOML output can be easily consumed by other frameworks or converted to application.yml. For polyglot projects using Python, Rust, or Go alongside Java services, TOML provides a shared configuration format understood by all components.

Q: How does TOML handle special characters in property keys?

A: TOML supports bare keys (alphanumeric, dash, underscore) and quoted keys for anything else. Property keys containing dots are split into table hierarchy, while keys with special characters are wrapped in quotes: "com.myapp.setting" = "value".

Q: What tools can validate the converted TOML file?

A: You can validate TOML files with online validators like toml-lint, the Python tomllib module (built into Python 3.11+), the Rust toml crate, or VS Code extensions. The strict TOML v1.0.0 specification ensures consistent parsing across all compliant tools.