A Java style properties file contains key value pairs (properties) in a file with ISO-8859-1 encoding (code page 28591). The file usually has a “.properties” file extension and consists of a series of lines (terminated by CRLF or CR or LF) each a key value pair, a comment or a blank line.

Leading whitespace (spaces, tabs ‘\t’, form feeds ‘\f’) are ignored at the start of any line – and a line that is empty or contains only whitespace is treated as blank and ignored.

A line where the first non-whitespace character is a ‘#’ or ‘!’ is a comment line and the rest of the line is ignored.

If the first non-whitespace character is not ‘#’ or ‘!’ then it is the start of a key. A key is all the characters up to the first whitespace or a key/value separator (‘=’ or ‘:’). The separator is optional. Any whitespace after the key or after the separator (if present) is ignored.

The first non-whitespace character after the separator (or after the key if no separator) begins the value. The value may include whitespace, separators, or comment characters.

The following special cases are defined:

'\t' - horizontal tab.
'\f' - form feed.
'\r' - return
'\n' - new line
'\\' - add escape character.
'\ ' - add space in a key or at the start of a value.
'\!', '\#' - add comment markers at the start of a key.
'\=', '\:' - add a separator in a key.

Any Unicode character may be inserted in either key or value using the following escape:

'\uXXXX' - where XXXX represents the unicode character code as 4 hexadecimal digits.

Finally, longer lines can be broken by putting an escape at the very end of the line. Any leading space (unless escaped) is skipped at the beginning of the following line.

Examples

a-key = a-value
a-key : a-value
a-key=a-value
a-key a-value

All the above will result in the same key/value pair – key “a-key” and value “a-value”.

! comment...
# another comment...

The above are two examples of comments. Yes, you can add comments to Java .properties files – so please do!

Hong\ Kong = Near China

The above shows how to embed a space in a key – the key is “Hong Kong” and the value is “Near China”. Without the ‘\’ escape, the key is “Hong” and the value is “Kong = Near China” (it wouldn’t be the first time I’ve seen it done…).

a-longer-key-example = a really long value that is \
split over two lines.

An example of a long line split into two.