JSON ⇄ Properties

JSON and Properties conversion: flattening, arrays, and encoding conventions

The Properties model is a flat key-value list

Java's .properties file (and the formats that follow it) is essentially a sequence of flat key-value lines:

db.host=127.0.0.1
db.port=3306
list=a,b

It has no nesting, no arrays, and no types — only string keys and string values. So when converting to and from JSON, the hierarchy must be expressed through convention, and these conventions are not standards; each framework implements its own.

Nesting uses dots, but a dot is part of the key name

Expanding JSON's {"db":{"host":"127.0.0.1"}} into db.host=127.0.0.1 is the most common practice (Spring Boot's relaxed binding is built around it).

The problem is ambiguity: a key name may legitimately contain a dot. The two JSON shapes below expand to exactly the same line:

• {"db":{"host":"x"}} becomes db.host=x
• {"db.host":"x"} becomes db.host=x

Reverse parsing cannot tell them apart. Some implementations escape the dot (writing db\.host) to disambiguate, but that is not standard and not all readers honor it. So the round trip is not strictly reversible: if a key name contains a dot, confirm the reader's convention first, or simply avoid dots in key names.

Arrays have no native representation

Properties holds only string values, so arrays rely on convention, and the three common forms are mutually incompatible:

None is perfect: the first is clearest but verbose; the third is simplest but splits wrongly when an element itself contains the delimiter (such as a comma-bearing URL or sentence) and needs extra escaping. This tool outputs one of these forms, so check it against the documentation of the framework you actually use rather than assuming it matches.

Encoding: the easiest place to get garbled text

Historically a .properties file is read as ISO-8859-1, so any non-ASCII character must be written as a \uXXXX escape — for example an accented Latin letter such as é is written as \u00E9, or a Japanese character such as テ as \u30C6, keeping the file itself pure ASCII. This is the long-standing Java-platform practice, justified by "a byte sequence is interpreted identically in any environment".

Newer versions (Java 9 and later for ResourceBundle and the default of PropertyResourceBundle) instead read as UTF-8. This creates a version difference:

• Writing full ASCII escapes reads correctly on both versions, the safest choice.
• Writing UTF-8 directly works on new versions but yields mojibake on old versions or on any reader configured for ISO-8859-1.

So for an uncertain runtime, the \uXXXX escape is the most robust approach. This tool can emit the escaped form when converting, which solves the problem of putting non-ASCII content into a config file.

Format details

The duplicate-key rule, like JSON, deserves caution: the overwrite is silent, with no warning.

How to use the tool

Both directions are supported: expand a nested JSON into dot-notation key lines, or restore dotted key lines into a nested structure. It can also emit non-ASCII characters as \uXXXX escapes to fit ISO-8859-1-reading environments.

Useful scenarios: turning Spring Boot's application.properties into JSON for programmatic processing or comparison, or generating the corresponding properties from a JSON config for a Java service. Everything runs locally in your browser, so configuration that includes database connection details never leaves your device.