README.md

Config Mate

Config Mate recursively resolves JSON References ($ref) across JSON, YAML, and XML configuration and writes one self-contained JSON, YAML, or XML artifact.

config-mate config/root.yaml --output build/config.yaml

Maintaining reusable policy, runtime profiles, workflows, and other generic configuration as named components keeps root documents focused on application intent. Config Mate collects those modular sources for downstream tools that only accept a single file.

Documentation

The documentation follows the Diátaxis structure:

• Tutorial: bundle your first configuration
• How to build a modular configuration
• How to use the playground
• CLI reference
• $ref reference
• Explanation: why modular configuration?
• Explanation: how the implementation is organized

Install

Config Mate requires Python 3.10 or newer. After configuring access to the package registry used by your organization:

python -m pip install config-mate
config-mate --help

Hatch projects

To add Config Mate to a named Hatch environment, configure the package index and dependency in pyproject.toml:

[tool.hatch.envs.prod.env-vars]
PIP_EXTRA_INDEX_URL = "https://token:{env:TOKEN_PYPI_REGISTRY}@git.terradue.com/api/v4/projects/{env:PYPI_PROJECT_ID}/packages/pypi/simple/"

[tool.hatch.envs.prod]
path = "/app/envs/my-hatch-env"
dependencies = [
  "config-mate",
]

If Config Mate is a runtime dependency of the package itself rather than a development environment, declare it under [project] instead:

[project]
dependencies = [
  "config-mate",
]

Quick example

Given components/runtimes.yaml:

python:
  image: python:3.13-slim
  replicas: 2

and config.yaml:

service:
  runtime:
    $ref: components/runtimes.yaml#/python

run:

config-mate config.yaml --ext json --output build/config.json

The output is a single JSON document with the referenced runtime inlined.

Playground

The Streamlit playground provides an editor for trying YAML references and viewing the resolved result:

task run_playground

See Use the playground for published-container, development-container, and direct-run instructions.

Local quality checks

Install Hatch and Taskfiles then install the Git hook:

task quality:pre-commit:install

Every commit runs Ruff (including the configured McCabe complexity limit), Ruff formatting, strict mypy checks, and the pytest suite. Run the complete hook explicitly with:

task quality:pre-commit:run

## License

[![Apache License, Version 2.0](https://img.shields.io/badge/license-Apache%20License%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)