Frequently asked questions

How is this different from a JSON Schema validator?

JSON Schema is more expressive and maxicfg does not try to compete with it. The difference is scope: maxicfg works on dotted keys across several merged files and knows about environments. If you only need to validate one document against a rich schema, a JSON Schema validator is the better tool.

Does it modify my files?

Only fmt and render write anything, and both support --check to run read-only. Every other command reads and reports.

Can it read configuration from Consul, etcd or Vault?

No, and this is unlikely to change. maxicfg operates on files in a repository. Reading from remote stores would mean handling authentication, caching and partial failures — a much larger tool than this one wants to be.

Why are keys written in dotted form?

Because the same logical key may be nested differently in YAML and flat in a dotenv file. Dotted notation gives one way to name a key regardless of the format it happens to live in.

How does it handle YAML anchors and aliases?

Anchors are resolved before validation, so the schema sees the expanded document. fmt preserves anchors rather than expanding them in place.

Is it fast enough for a large repository?

Parsing dominates the runtime. On a repository with roughly 400 configuration files totalling 3 MB, a full lint takes about 240 ms on a laptop. Files are parsed in parallel across available cores.

Does it support Windows?

Yes. Release binaries are published for windows/amd64 and windows/arm64. Path handling is normalised, so schemas written on Linux work unchanged.

What happens with duplicate keys in one file?

A duplicate key is an error, not a silent override. YAML parsers disagree on which occurrence wins, so the only safe answer is to refuse the file.

Can I use it as a Go library?

The packages under internal/ are not importable by design. A stable public API is planned for 1.0, but until then the command-line interface is the supported entry point.

Why is it not 1.0 yet?

Two reasons. The schema format still has rough edges around list validation, and the diff output format is likely to change once profile comparison stabilises. Both would be breaking changes, so the version number stays below 1.0 until they settle.

How do I report a bug?

Open an issue in the project repository with the output of maxicfg version and a minimal configuration file that reproduces the problem. Redact any real credentials first — and if the bug involves scan, replace them with obviously fake values rather than removing the lines entirely.