What is the minimum config I need to run the router?

A graph.token (or a static execution config path) and a listen address. Everything else has a sensible default.

Can I split config across more than two files?

Yes. CONFIG_PATH takes any number of comma-separated paths.

How do list fields merge across files?

They do not merge: later files replace the list wholesale.

Where does the JSON schema live?

Reference the JSON Schema from your YAML header (for example https://raw.githubusercontent.com/wundergraph/cosmo/main/router/pkg/config/config.schema.json). VS Code with the YAML extension and JetBrains IDEs pick it up automatically.

Does env-var expansion run before or after validation?

Before. Variables are expanded, then the final document is validated. A missing env var results in an empty string, which the schema will reject if the field is required.

What happens if I reference a deprecated field?

Your IDE can flag it from the JSON Schema while you edit. At router boot the merged configuration is validated again, and deprecated options usually show up as log warnings so operators see them early—check the configuration reference for the specific field when you upgrade.

GraphQL Router Configuration | Cosmo by WunderGraph

The problem

Config should fail in the editor, not in prod

Typed YAML, env expansion, and merges turn router config into something you can review like code.

Errors show up at runtime

A typo in a field name, a missing required setting, a deprecated option: none of that surfaces until the router boots. At that point, you are rolling back in production.

Every environment needs a different config

Dev, staging, and production share most settings but differ on URLs, log levels, and feature flags. Teams copy-paste full files per environment or reach for a templating tool that now owns your deploy process.

Secrets leak into config files

API tokens and credentials need to be in the config at runtime. If they live in the file, they end up in git.

Our solution

Catch configuration mistakes in your editor before deploy

Cosmo Router configuration is YAML validated against the JSON Schema, with environment variable expansion and multi-file merging, so mistakes show up while you type.

Point the YAML language server at the router JSON Schema from the top of your file (see the official configuration docs for the exact `$schema` URL). VS Code with the Red Hat YAML extension and JetBrains IDEs pick up auto-completion, hover documentation, and invalid or deprecated values while you edit.
Use `${VAR_NAME}` placeholders in YAML for values that should come from the process environment. The router expands them before schema validation so tokens and other secrets do not need to live in the file you commit.
Pass several files through `CONFIG_PATH` as a comma-separated list (or pass `--config` multiple times). Each file is validated, then merged in order, and later files override earlier keys for the same setting, which covers base plus per-environment overlays without an external templating step.

Same binary everywhere, different overlay files per environment.

Before & after

Validation & secrets

Before Cosmo	With Cosmo
Config errors discovered when the router fails to boot	JSON schema catches typos and invalid values in the editor
Per-environment config duplication or external templating	Base file + override file per environment, merged by CONFIG_PATH
Secrets checked into config files	`${VAR_NAME}` expansion pulls secrets from env at runtime
No IDE help for config discovery	Auto-completion, hover docs, deprecation warnings in VS Code and JetBrains

Config merging rules

Precedence

Environment variables are lowest precedence
YAML configurations override environment variables
Later files in `CONFIG_PATH` override earlier files
List values are replaced wholesale, not concatenated
An empty value in a YAML file overrides a non-empty default

Configuration examples

Multi-environment setup · IDE schema header

Layer `prod` overrides on `base`, launch with `CONFIG_PATH`, and pin the schema for completions.

1

2

3

4

5

6

7

How router configuration is loaded

01

Merge order is deterministic.

Load config file(s)

Router reads `config.yaml` in the working directory by default, or path(s) set in `CONFIG_PATH`. Multiple comma-separated paths load in order, with later files overriding earlier ones.

02

Secrets stay out of Git.

Expand environment variables

Any `${VAR_NAME}` reference is replaced with the value of that environment variable. An override env file can also be loaded via `OVERRIDE_ENV`.

03

Fail fast before traffic.

Validate against the schema

Final merged configuration is validated against the JSON Schema. Type mismatches, missing required fields, and invalid enum values are reported with the offending path.

04

Invalid config fails before listening.

Apply and run

Fields such as intervals expect Go duration strings (`10s`, `5m`, `1h`) where the schema defines them. When validation succeeds, the router starts with the merged configuration applied.