INI vs Java .properties — when to use which

INI and Java .properties files are both line-oriented key–value formats: humans can edit them in a text editor, parsers are small, and they predate JSON-heavy stacks. They solve similar problems—application settings—but with different layout rules and ecosystem defaults. Picking the right one avoids surprise when you merge configs, migrate to JSON, or hand a file to another tool.

What INI looks like

INI groups settings under section headers in square brackets. Each section holds key=value lines; keys before the first [section] live at the root of the file.

; comment with semicolon
# comment with hash is also common
appName = LocalTools
debug = true

[database]
host = 127.0.0.1
port = 5432

[cache]
enabled = false
ttl = 3600

Typical INI traits:

• Sections give you named buckets without dot-separated key names.
• Comments often use ; or # (dialects vary).
• Values are usually strings until a tool coerces booleans or numbers; quoting handles spaces and special characters.
• No standard spans every INI dialect—Windows, PHP, Git, and game engines each have small differences (duplicate keys, interpolation, case sensitivity).

INI is a good fit when authors think in “open a section, set keys” and when the file is flat or shallow (a handful of sections, scalar values).

What Java .properties looks like

The Java Properties format is intentionally flat: one logical map from string keys to string values. There are no [sections] in the file itself; hierarchy is expressed with dotted keys (server.host=127.0.0.1) or separate files loaded in order.

# comment
! bang comments are allowed too
appName=LocalTools
server.host=127.0.0.1
server.port=8787
long.message=This value continues \
  on the next line because of a trailing backslash
unicode.greeting=Hello \\u0041

Typical .properties traits:

• Separators can be = or : (first wins on the line).
• Line continuation: a trailing \ joins the next physical line (whitespace rules matter).
• Escape sequences: \n, \t, \r, \f, and \uXXXX Unicode escapes are part of the Java spec.
• Comments start with # or !.
• Spring, Maven, Gradle, and many JVM libraries load .properties or layered variants by convention.

Use .properties when you are in the Java/JVM ecosystem, when frameworks expect dot keys or classpath resource bundles, or when you need spec-backed escape and continuation behavior.

Side-by-side: when to lean INI vs .properties

Concern	Lean INI	Lean .properties
Natural structure	A few named sections with scalar keys	One flat namespace; nesting via dots
Primary ecosystem	Windows, PHP, legacy apps, some games/tools	Java, Spring, Android-style resource bundles
Comments	; and/or # (tool-dependent)	# and ! (Java rules)
Multi-line values	Quote or dialect-specific rules	Trailing \ continuation is standard
Unicode in values	Depends on file encoding and tool	\uXXXX escapes are defined
Interchange with JSON	Sections become nested objects	Nested JSON becomes flattened dot keys

Neither format is a great API wire format today—JSON (or YAML/TOML for hand-edited trees) usually wins for new services. INI and .properties remain excellent for local defaults, installer snippets, and framework bootstrap files.

JSON as a bridge (and where conversion gets lossy)

Converting to JSON gives you a single tree you can validate, diff, or feed into other tools:

• INI → JSON: each [section] becomes a nested object; root keys stay at the top level.
• JSON → INI: nested objects whose values are all scalars become sections; deeper nesting or arrays are often emitted as JSON on one line because classic INI has no standard for arrays.
• JSON → .properties: nested objects flatten to sorted dot keys (parent.child=value) for stable, diff-friendly output.

Watch for these pitfalls when round-tripping:

• Type coercion: parsers may turn true / 42 into JSON booleans and numbers; exporting back might stringify them differently than the original file.
• Duplicate keys: last write wins in many parsers; duplicates are easy to miss in review.
• Section vs key name clash: a root key database and a section [database] cannot coexist in strict parsers.
• Arrays and rich nesting: prefer JSON (or TOML) as the source of truth if the config is not a shallow map.

Related formats in the same neighborhood

• .env files target process environment variables (export KEY=value), not arbitrary nested trees.
• TOML is a modern, typed config language with explicit tables—often chosen when INI feels too loose but YAML feels too heavy.
• JSON vs YAML for config covers the formats most new projects standardize on for interchange and CI.

Try it locally in your browser

Use the INI / Java properties ↔ JSON tool to paste INI or .properties, convert to JSON, edit the tree, and emit INI or flattened .properties again—all without uploading your config. To pretty-print or validate the JSON side, open the JSON Formatter & Validator.

Related reading

• JSON vs YAML for config — choosing formats for new hand-edited config.
• What is TOML? — typed tables when INI-style sections are not enough.
• .env files: syntax, merging, and secrets hygiene — environment-variable files vs structured config files.