# HOCON resolver

- Human page: https://happytails.ai/en/developer-tools/hocon-resolver/
- Markdown: https://happytails.ai/en/developer-tools/hocon-resolver.md
- Structured JSON: https://happytails.ai/agents/en/developer-tools/hocon-resolver/index.json
- Visibility: public

## Tool capabilities

| Property | Value |
| --- | --- |
| Tool ID | `hocon-resolver` |
| Category | developer-tools |
| Implementation | Registered implementation. Registration alone is not a production-quality guarantee. |
| Browser execution | Use the visible action or interactive controls. |
| Browser processing | Browser; see tool notes for network behavior. |
| HTTP API | Not callable through HTTP. |
| Browser-agent interface | run_current_tool |

### Implementation notes

Resolves HOCON on your device, including substitutions, merges and includes between the files you paste. Up to 500,000 characters and 200 files.

### Inputs and settings

Text input: HOCON configuration.

Example or placeholder shown in the interface (not a validated fixture):

```text
app {
  port = 8080
  url = "http://localhost:"${app.port}
}
```

Paste application.conf. Start each included file with ### file: and its name. Up to 500,000 characters. Review the settings before running.

| Setting | Meaning | Control type | Default | Constraints |
| --- | --- | --- | --- | --- |
| `substitutions` | Variables | textarea | "" |  |
| `name` | Main file name | text | "application.conf" |  |

### Browser-agent workflow

1. Open the human page in a browser that supports WebMCP.
2. Discover the interface exposed by that page; use its actual schema.
3. Select files on the page first when the tool requires files.
4. Call `run_current_tool` with valid input and settings.
5. Inspect the returned result or error and the displayed output. Retrieve files from the displayed download links.

Calls do not automatically copy or download results. Browser permissions still apply. Interface availability alone is not proof of successful execution.

### Planning specification

Up to 500,000 characters in total, 200 files and 50 nested includes. Everything runs on your device in a background worker. Downloads: resolved.json, a JSON report with includes and origins, and a CSV of origins.

This describes intended requirements. Use the implementation notes, interface schema and observed output to determine current support.

### Complete machine-readable capability record

```json
{
  "id": "hocon-resolver",
  "category": "developer-tools",
  "built": true,
  "requirements": "Up to 500,000 characters in total, 200 files and 50 nested includes. Everything runs on your device in a background worker. Downloads: resolved.json, a JSON report with includes and origins, and a CSV of origins.",
  "implementation": {
    "fields": [
      {
        "key": "substitutions",
        "label": "Variables",
        "value": "",
        "type": "textarea",
        "help": "Optional. NAME=value lines used when a substitution is not found in the files, like environment variables."
      },
      {
        "key": "name",
        "label": "Main file name",
        "value": "application.conf",
        "type": "text",
        "help": "Name of the first file. Add include files after a line ### file: name."
      }
    ],
    "registrationFamily": "config-infrastructure-json",
    "inputMaxLength": 500000,
    "inputErrorCode": "CONFIG_INFRASTRUCTURE_JSON_TOO_LONG_HOCON",
    "note": "Resolves HOCON on your device, including substitutions, merges and includes between the files you paste. Up to 500,000 characters and 200 files.",
    "experience": {
      "automatic": false,
      "single": false,
      "inputMaxLength": 500000,
      "inputMode": "text",
      "label": "HOCON configuration",
      "placeholder": "app {\n  port = 8080\n  url = \"http://localhost:\"${app.port}\n}",
      "help": "Paste application.conf. Start each included file with ### file: and its name. Up to 500,000 characters. Review the settings before running.",
      "action": null
    },
    "mode": "explicit",
    "interactive": false
  },
  "execution": "Browser interface",
  "api": null,
  "browser_agent": {
    "supported": true,
    "name": "run_current_tool",
    "discovery": "WebMCP on the human page in a supporting browser",
    "verification": "See audit/API-AUDIT.md; availability is not verification"
  }
}
```

## Page guide

Resolve a HOCON configuration, such as application.conf for Akka, Play or Spark, into plain JSON. See the final value of every key, which file and line set it, and how substitutions, merges and includes combined.

How can we improve this tool?

Report a problem or share an idea.

Please leave out private information. Your message and the tool name go to our team via PostHog.

### How to use HOCON resolver

1. Paste application.conf. Add included files after a line ### file: name, such as ### file: db-defaults.conf.
2. Optionally add NAME=value variables that substitutions may fall back to, like environment variables.
3. Run the resolver and check the resolved JSON and the origin of each value.
4. Download resolved.json, the JSON report or the CSV of origins.

## Useful next steps

- [JSON formatter](https://happytails.ai/en/developer-tools/json-formatter/) ([Markdown](https://happytails.ai/en/developer-tools/json-formatter.md))

- [TOML to JSON](https://happytails.ai/en/data-tools/toml-to-json/) ([Markdown](https://happytails.ai/en/data-tools/toml-to-json.md))

- [YAML to JSON](https://happytails.ai/en/data-tools/yaml-to-json/) ([Markdown](https://happytails.ai/en/data-tools/yaml-to-json.md))

## How it resolves

Happytails.ai parses and resolves HOCON following the specification in lightbend/config (HOCON.md, Apache-2.0, read on 16 October 2026). Duplicate keys merge objects and later plain values win, a.b.c keys create nested objects, values on one line are concatenated, and ${path} substitutions look at the final configuration, while a key that refers to itself sees its earlier value. When substitutions refer to each other in a loop, the loop is broken by looking back at an earlier value of one of its keys; a loop with no earlier value to fall back on is reported as a cycle. a += b appends to a list.

### Includes and variables

include "name" is resolved relative to the including file among the files you paste; without an extension it tries .properties, .json and .conf and merges them. Substitutions inside an included file are tried at the include point first and then from the root. When a path is not defined, the variables box is used like environment variables, including ${NAME\[\]} for NAME\_0, NAME\_1 lists.

### Conformance and limits

The parser passes the equivalence tests from the lightbend/config repository (equiv01 to equiv05), which are bundled with their Apache-2.0 notice for the automated checks. url() includes, Java system properties, duration and size conversions and the conversion of numbered keys to lists are not applied.