> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.ampdb.io/api/mcp` to find what you need.

# Config Map Format

Status: Unstable.

A [config map](/managing-amp/config-maps)'s document is a JSON object. You can write it in JSON or TOML, and keep values
out of it, like credentials, by writing references to environment variables instead. This page
covers both, and the rules a document must follow.

What fields a document holds depends on its kind: an `evm-rpc` config map holds an [EVM RPC provider's
configuration](/providers/evm-rpc), an `adbc-postgres` one a [PostgreSQL
destination's](/managing-amp/pipelines/postgresql).

## JSON and TOML

Amp stores and returns documents as JSON. `ampctl` also accepts TOML, which it converts to JSON before sending, so TOML
never reaches Amp. These two files make the same config map:

:::code-group
```toml [mainnet_rpc.toml]
kind = "evm-rpc"
network = "mainnet"
url = "https://ethereum-rpc.example.com"
auth_token = "${{ env.MAINNET_RPC_TOKEN }}"
```

```json [mainnet_rpc.json]
{
  "kind": "evm-rpc",
  "network": "mainnet",
  "url": "https://ethereum-rpc.example.com",
  "auth_token": "${{ env.MAINNET_RPC_TOKEN }}"
}
```
:::

`ampctl configmap create` and `ampctl configmap update` read a file's format from its extension: `.toml` or `.json`.
They reject any other extension, rather than guessing the format from the content:

```text
✗ failed to load config map document
  → unsupported config map file extension for ./mainnet_rpc.txt: expected .json or .toml
```

The Admin API only takes JSON: the document goes in the request body's `data` field. See
[Create a config map](/managing-amp/config-maps#create-a-config-map).

### Rules

* **The top level is an object.** A document that's an array, a string, or a number is rejected with
  `INVALID_CONFIGMAP_DATA`. A TOML file is always an object.
* **At most 1 MiB**, measured as JSON. A larger document is rejected with `CONFIGMAP_TOO_LARGE`, and `ampctl` refuses
  it before sending.
* **Anything else goes.** Amp doesn't check a document against its kind: a document with a missing or misspelled
  field is accepted.

### What you get back

Amp keeps a document's content, not its text. When you read a config map back, its keys may come in a different order,
and a key you wrote twice comes back once, with one of its values. So a document you read back is equal to the one you
wrote, but not the same file. TOML comments are gone, too, since they never reach Amp.

A top-level `kind` key stays in the document. The config map's kind is a separate field: `ampctl` takes it from that key
when you don't pass `--kind`, but the two can differ.

## Environment variable references

To keep a value out of the stored document, write a reference to an environment variable in its place:

```toml
auth_token = "${{ env.MAINNET_RPC_TOKEN }}"
```

Amp stores the reference as you wrote it, and returns it as it is. In this release, no part of Amp loads config maps, so
nothing fills references in yet.

### Syntax

A reference is `${{ env.NAME }}`:

* `${{` and `}}` open and close it. Spaces inside are optional: `${{env.NAME}}` works too.
* `env.` says the value comes from the environment. It's required.
* `NAME` is the variable's name: letters, digits, and underscores.

A reference can sit inside a longer string, and a string can hold several:

```toml
url = "https://${{ env.RPC_HOST }}/v1/${{ env.RPC_PROJECT_ID }}"
```

Amp doesn't check references when you write a config map: a malformed one is stored like any other text.

### `${VAR}` is not a reference

Provider configurations use `${VAR}` for environment variables. In a config map, `${VAR}` is plain text, which Amp
stores and returns as it is, with no error and no warning. Always write `${{ env.VAR }}`.

See [Secrets in Config Maps](/managing-amp/config-maps/secrets#the-var-trap).