---
url: https://findutils.com/guides/properties-to-json
title: "Properties to JSON: Choose Flat Keys or Nested Objects"
description: "Convert Java Properties to JSON with flat or nested keys. Check escapes, duplicate definitions, arrays and string values before exporting the converted file."
category: developer
content_type: guide
guide_type: subtopic
cluster: configuration
locale: en
read_time: 7
status: published
author: "olgunozoktas"
published_at: 2026-09-08T07:14:00Z
updated_at: 2026-09-08T07:14:00Z
excerpt: "Dotted property names can remain literal keys or become nested JSON. Learn which shape fits your destination and how to identify values that a conversion changes."
tag_ids: ["java", "properties", "json", "configuration"]
tags: ["Java", "Properties", "JSON", "Configuration"]
primary_keyword: "properties to json"
secondary_keywords: ["java properties to json", "json to properties", "application.properties to json", "properties nested json", "properties unicode escapes"]
tool_tag: "properties-json-converter"
related_tool: "properties-json-converter"
related_tools: ["properties-json-converter", "json-formatter", "env-json-converter"]
og_image: "/images/content/guides/properties-to-json-flat-nested.webp"
image_alt: "Blue threads connect dotted paper strips to nested rectangular frames, beside a separate flat arrangement of strips."
---

Convert Properties to JSON with **Flat** when the destination expects complete property names such as `app.name`. Select **Nested** when it expects an `app` object with a `name` property. FindUtils [Properties JSON Converter](/developers/properties-json-converter/) supports both shapes and reports duplicate definitions.

This guide explains how to select the shape, inspect escapes, and convert JSON back into properties. The examples contain invented settings, so you can compare the results without using private configuration.

## Why does the JSON shape matter?

A dotted property name does not automatically define a nested object. `java.util.Properties` stores string keys and values. The application that reads those strings determines their meaning. See the [Java Properties documentation](https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/Properties.html).

The FindUtils **Nested** option applies an additional conversion rule. It splits dotted names into objects. It also interprets suffixes such as `[0]` as array positions.

- **Literal names:** A consumer can expect the complete key `app.name`.
- **Object structure:** Another consumer can expect a `name` field inside `app`.
- **Conflicts:** `app=demo` and `app.name=notes` need two literal keys, but compete for one nested location.

Choose the required shape before you interpret the output. Nested JSON can be easier to read without being the correct import format.

## How to convert Properties to JSON

Use the same sample in both modes to see the difference. Leave automatic value conversion off for the first check.

### Step 1: Load the properties sample

Open the [Properties JSON Converter](/developers/properties-json-converter/). Select **.properties to JSON**. Paste the following sample. You can also select a local `.properties` file.

```properties
app.name=Field Notes
server.port=8080
app.enabled=false
app.features[0]=search
app.features[1]=export
app.welcome=Merhaba d\u00fcnya
```

### Step 2: Inspect the default nested result

Leave **Shape** set to **Nested**. Leave **Numbers and booleans** off. The result contains two top-level keys. The two feature entries become one array.

```json
{
  "app": {
    "name": "Field Notes",
    "enabled": "false",
    "features": ["search", "export"],
    "welcome": "Merhaba dünya"
  },
  "server": {
    "port": "8080"
  }
}
```

The top-level keys are `app` and `server`. The converter's six-key count refers to distinct input property names. It does not count the output's top-level objects.

### Step 3: Compare the flat result

Select **Flat**. Each original property name remains a complete JSON key. The Unicode escape still decodes into its character. Values still remain strings.

```json
{
  "app.name": "Field Notes",
  "server.port": "8080",
  "app.enabled": "false",
  "app.features[0]": "search",
  "app.features[1]": "export",
  "app.welcome": "Merhaba dünya"
}
```

### Step 4: Select the required value types

Enable **Numbers and booleans** only when the JSON consumer expects typed values. For this sample, `8080` becomes a number and `false` becomes a boolean. The feature names and welcome message remain strings.

### Step 5: Review warnings before export

Read every duplicate, Unicode, or shape warning. Copy the result or download `converted.json`. Keep the original document if it contains comments or layout that you need later.

## Examples of property rules that affect the output

Properties syntax has rules beyond a simple split at an equals sign. This converter handles colon separators, whitespace separators, continuation lines, and backslash escapes.

### Separators and comments

These three lines express the same key and value:

```properties
app.name=Field Notes
app.name:Field Notes
app.name Field Notes
```

Use one form in a real file. If you paste all three, the converter reports duplicate definitions and keeps the final value.

A properties comment starts with `#` or `!` after optional leading whitespace. A hash inside a value remains part of that value. For example, `label=Use #blue` retains `Use #blue`.

Quotation marks are ordinary value characters in this format. `label="demo"` includes the quote characters in the value. Do not apply dotenv quote rules to Java properties.

### Continuation lines

A line with an odd number of trailing backslashes continues onto the next line. The parser removes the continuation marker and the next line's leading whitespace.

```properties
message=First \
    second
```

The value becomes `First second`. The space before the continuation marker remains. Without that space, the two words join as `Firstsecond`.

Two trailing backslashes represent a literal backslash instead of a continuation. Count the characters when a path or message ends unexpectedly.

### A nested name conflict

This input defines two separate properties:

```properties
cache=local
cache.ttl=60
```

**Flat** preserves both names. **Nested** creates `cache` as an object containing `ttl`. It drops the standalone `cache` value and reports that conflict.

Do not accept the nested result if `local` remains necessary. Keep the flat shape or choose a new data model with the destination owner.

## Flat, nested, and reverse conversion

Choose the mode from the consumer's contract. The reverse direction always flattens nested JSON; the forward shape option does not change that rule.

| Task | Mode or setting | Main limitation |
|---|---|---|
| Preserve complete dotted names | Properties to JSON, Flat | Values remain strings unless conversion is active |
| Inspect groups as objects | Properties to JSON, Nested | A value can conflict with a parent object |
| Produce typed JSON | Numbers and booleans on | The tool does not validate an application schema |
| Create properties from JSON | JSON to .properties | Object paths become dotted names; arrays use indexes |
| Write portable non-ASCII text | Escape non-ASCII as `\uXXXX` on | The receiving loader still determines the encoding rules |

For example, this reverse input contains a string, an array, and a null:

```json
{"app":{"name":"Field Notes","features":["search","export"],"note":null}}
```

The output contains four property lines:

```properties
app.name=Field Notes
app.features[0]=search
app.features[1]=export
app.note=
```

Null becomes empty text. Empty objects and empty arrays produce no property lines. A later conversion cannot reconstruct those empty containers from their absent entries.

## Common mistakes and corrections

Check the actual input format and loader before you treat a conversion result as ready for use.

### Mistake 1: Using the dotenv converter

Java properties and dotenv use different separator, comment, and escape rules. Use [Env JSON Converter](/developers/env-json-converter/) for dotenv input. Use the Properties converter for Java property syntax.

### Mistake 2: Accepting a malformed Unicode escape

This converter keeps a malformed Unicode escape literally and adds a warning. Java's `Properties.load` rejects malformed Unicode escapes. Correct the escape before you use the output as a Java configuration file.

### Mistake 3: Assuming every properties loader uses UTF-8

`Properties.load(InputStream)` uses ISO-8859-1. `Properties.load(Reader)` uses characters from the supplied reader, whose setup determines byte decoding. It is not automatically a UTF-8 reader. See the [Java loader contract](https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/Properties.html#load(java.io.Reader)).

Keep Unicode escapes active for output that needs them. If uploaded text already contains incorrect characters, escapes cannot restore the original bytes. Decode the original file correctly before conversion.

### Mistake 4: Treating a conversion as a configuration merge

The tool converts one document. It does not combine profiles, apply framework precedence, expand placeholders, or calculate the settings of a running application.

### Mistake 5: Expecting a lossless return trip

Comments, duplicate definitions, original separators, and empty containers do not survive every conversion. Compare values and structure against an explicit acceptance list. Do not use byte equality as the only check.

## Tools used in this guide

FindUtils provides a separate conversion tool for each relevant source format.

- [Properties JSON Converter](/developers/properties-json-converter/) handles property parsing, JSON shape, and reverse output.
- [JSON Formatter](/developers/json-formatter/) makes the resulting JSON easier to inspect.
- [Env JSON Converter](/developers/env-json-converter/) handles dotenv when the source is an environment file.

## FAQ

**Q: Which mode preserves dotted property names?**
A: Flat mode. A name such as `server.port` remains one JSON key.

**Q: Does Nested mode preserve every value?**
A: Not when a value conflicts with a nested parent. The converter reports the conflict and keeps the nested object.

**Q: Does the converter keep numbers as strings?**
A: Yes, by default. Enable Numbers and booleans when the destination requires typed JSON values.

**Q: Do comments survive JSON conversion?**
A: No. Keep the original properties document if its comments explain the configuration.

**Q: Does the tool upload my file?**
A: The converter processes the input in the browser. The page can still load advertisements and other external resources. Use sanitized data for a shared review.

**Q: Does the converter require an account or provide an API?**
A: The browser page does not require an account. This converter currently has no REST or MCP version.

## Next steps

Use the [configuration conversion review](/blog/config-conversion-review-checklist/) to record accepted changes. Read the [ENV to JSON guide](/guides/env-to-json/) for dotenv rules. Read the [JSON to TOML guide](/guides/json-to-toml/) for table, array, and null handling.