Skip to content
ROOT

konfig Plan

A CLI configuration validator. YAML/TOML/JSON config files validated against schemas (JSONSchema or Pydantic models). Year 1 Phase 4 Python-fluency stretch deliverable. Used in basecamp CI from Year 2 onward to validate Helm values before merge.

konfig is the stretch fluency artifact for Year 1 Phase 4 — shipped after rxp if Phase 4 has time. Like the other Group C fluency artifacts, it’s deliberately small, quiet-shipped, and earns a real production role inside the platform later.

The role konfig earns: from Year 2 onward, basecamp’s CI pipeline runs konfig against every PR to validate Helm values and Kubernetes manifests before merge. That’s the difference between a fluency artifact (proves you can ship Python) and a production tool (catches drift before it deploys). konfig’s generate-schema mode also makes onboarding new schemas low-friction — the typical adoption blocker for validation tools.

The underlying pattern is schema-on-read-vs-write: schema validation at write time is what makes schema-on-write actually work. konfig is that discipline made portable — a CLI you can drop into any pre-commit hook or CI job.

What it is

A typer-based Python CLI:

Terminal window
konfig validate ./config.yaml --schema ./schema.json
# → ✓ valid, OR clear errors with line + column + actual-vs-expected


konfig validate ./configs/ --schema-dir ./schemas/  # bulk mode
# → validates every file in configs/ against matching schema


konfig generate-schema ./example.yaml > schema.json
# → infers JSONSchema from a sample

Why it exists

  1. Phase deliverable: Year 1 Phase 4 Python fluency stretch artifact
  2. Real tool: ROOT has dozens of YAML files (K8s, terraform tfvars, Helm values, GitHub Actions). A schema validator catches drift before deploy.
  3. Y2+ integration: Used in basecamp CI to validate Helm values + K8s manifests before merge. This is what makes konfig NOT just a fluency artifact — it earns a production role in the platform’s CI pipeline.

Pattern it teaches

schema-on-read-vs-write: schema validation is the discipline that makes schema-on-write work.

Also reinforces:

Scope

v1 (Year 1 Phase 4: quiet ship; STRETCH if time)

[ ] typer CLI: validate, validate-bulk, generate-schema, diff-schema
[ ] Support: JSONSchema, Pydantic models, OpenAPI fragment
[ ] Input formats: YAML, TOML, JSON
[ ] Error messages: line + column + actual vs expected + suggested fix
[ ] Bulk mode: directory of configs against directory of schemas
[ ] Generate schema from example (infer types + required fields)
[ ] >80% test coverage
[ ] README + examples (K8s manifest, GH Actions, terraform.tfvars)
[ ] Published to TestPyPI
[ ] Quiet ship

v2 (deferred)

  • Custom DSL for common patterns (e.g., “K8s manifest” preset)
  • VSCode extension
  • GitHub Action wrapper

Stack

  • Python 3.12+
  • typer (CLI)
  • pydantic v2 (model schemas)
  • jsonschema (JSON Schema validation)
  • ruamel.yaml (YAML with line tracking)
  • rich (terminal errors)

When built

Year 1 Phase 4, Month 4-5 (after rxp ships). Ships to github.com/abukix/konfig + TestPyPI as a stretch artifact.

Dependencies

konfig is standalone in Year 1. The Y2+ integration creates a downstream dependency: basecamp’s CI pipeline relies on konfig being installable and stable, so any breaking change to konfig’s CLI surface must be coordinated with basecamp’s CI.

Deliverables checklist

[ ] github.com/abukix/konfig public (quiet ship)
[ ] All commands working
[ ] Published to TestPyPI
[ ] README + usage examples
[ ] CI: tests on PR
[ ] Tagged release
[ ] Used in basecamp CI to validate Helm values + K8s manifests (Y2+)

Public vs private

Public quiet ship from Year 1 Phase 4. No launch energy.

Cross-references