Core specification
docuconf is a typed contract between an application and the platform that runs it. The app declares its configuration once, in its language's leading config library, and exports a ConfigContract (apiVersion: docuconf.dev/v1alpha1). The platform checks everything it will supply against that contract before deploying, and the app's SDK checks the real environment again at boot.
This specification has four parts:
| Part | Answers |
|---|---|
| Inputs | What an app can declare: 9 variable types, 6 file types, where values and files come from, how they are written into the environment, how injected secrets (and the pod annotations that enable their injectors) and config-file overlays fit in, and how lengths are counted. |
| Outputs | Everything generated from a contract, from the contract itself to Helm schemas and pod configuration, and what each output is for. |
| Generated docs | Where each input's description and details come from, and how docuconf docs turns the contract into CONFIG.md for developers and CONFIG.agents.md for agents. |
| SDK requirements | What every language SDK must support to conform, the boot-time error codes, and where each SDK stands today. |
Status: v1alpha1
Fields may still change. The normative text is SPEC.md, with its CUE meta-schema in spec/cue. These pages summarise it, and mark each item as Implemented, Specified, not built, or Planned.
One contract, three checks
app repo (CI)
declaration ──export──▶ contract.cue ──▶ published with the image digest
│
platform (CI, Crossplane or Helm) ▼
values + file sources + policy ──▶ validate ──▶ render ──▶ pod env, volumes, overlays
│
runtime ▼
injectors (Bank-Vaults, Vault Agent…) ──▶ process environment ──▶ SDK checks at boot| When | Who | Catches |
|---|---|---|
| CI of the platform repo | docuconf vet | Wrong types, out-of-range values, typos, missing inputs, policy violations — before merge. |
| Composition or install | Crossplane function, Helm values.schema.json | Bad values that reached the cluster anyway, and contract/image skew. |
| Boot | The language SDK | What the platform cannot see: secret contents, injected values, certificate expiry and key match, file contents. |
A contract, briefly
// Code generated by docuconf. DO NOT EDIT.
package orders
import "docuconf.dev/contract"
contract.#Contract & {
apiVersion: "docuconf.dev/v1alpha1"
kind: "ConfigContract"
metadata: {name: "orders-api", appVersion: "2.3.0", generator: {language: "go", sdk: "docuconf-go", version: "0.1.0"}}
vars: {
DATABASE_URL: {type: "url", description: "Primary Postgres connection string", required: true, secret: true, schemes: ["postgres"]}
PAYMENTS_TIMEOUT: {type: "duration", description: "Timeout for the payments service", default: "5s", max: "30s", encoding: "go"}
KAFKA_BROKERS: {type: "list", description: "Kafka brokers", required: true, items: "string", encoding: "csv", minItems: 1}
}
files: {
"serving-tls": {type: "tls", description: "Serving certificate", required: true, path: "/etc/orders/tls", dnsNames: ["orders.internal"], minRemaining: "720h"}
"tax-rates": {type: "config", format: "yaml", description: "Tax rates by country", path: "/etc/orders/tax/rates.yaml", schema: {...}}
}
}The contract is plain data. It records what the app accepts, including how its library parses lists and durations, so the platform can write values the app will read correctly. It never contains a secret.
What is generated today
| Output | Artifact | Produced by | Consumed by | Status |
|---|---|---|---|---|
| Contract (CUE) | contract.cue | Every language SDK’s export | The platform: docuconf CLI, CUE, Crossplane, Helm | Implemented |
| Contract (JSON) | contract.json | cue export, docuconf helm | Tools without CUE; the Helm library chart (files/docuconf/contract.json) | Implemented |
| Validation report | one line per problem; exit code 1 | docuconf vet, #Validate | CI before merge; the Crossplane function at composition | Implemented |
| Pod configuration | env, volumes, volumeMounts, configMaps, restartTriggers, podAnnotations, podLabels | docuconf render, #Render | Deployments and other pod templates | Implemented |
| Helm values schema | values.schema.json + files/docuconf/contract.json | docuconf helm, #HelmValuesSchema | Helm 3 and 4 on lint, template, install and upgrade | Implemented |
| Helm library chart | docuconf.env, .volumes, .volumeMounts, .configMaps, .reloaderAnnotations, .podAnnotations, .podLabels | helm/docuconf chart | App charts | Implemented |
| Boot-time violation report | all violations with stable error codes; /dev/termination-log | Each language SDK at startup | Operators, kubectl describe pod | Implemented |
| Config-file overlay | a host-format file (appsettings.Production.json, application.yml, Config.toml) in a ConfigMap | docuconf render and the Helm library chart, for variables the platform routes to an overlay | Hosts that layer config files: .NET, Spring, Rails, figment, Hoplite | Implemented |
| Configuration docs | CONFIG.md for developers, CONFIG.agents.md for coding and ops agents | docuconf docs | Developers, AI agents, an AGENTS.md or llms.txt | Implemented |
| Docs model | docs.json (kind ConfigDocs, apiVersion docs.docuconf.dev/v1alpha1) | docuconf docs --format model | Renderers: the CLI, a website, an MCP server, a Backstage plugin | Implemented |
The full list, including what is specified and planned, is on Outputs.
Frequently asked questions
What is a docuconf configuration contract?
A ConfigContract (apiVersion docuconf.dev/v1alpha1) is a CUE document that an application exports from its own config declaration. It lists every environment variable and file input the app reads, with its type, constraints, whether it is required or secret, and how the app parses it. The Kubernetes platform validates what it will supply against the contract before deploying, and the SDK validates the real environment again at boot.
What input types can a docuconf contract describe?
Nine variable types (string, int, float, bool, duration, url, enum, list, json) and six file types (config files in JSON, YAML or TOML; TLS key pairs; CA bundles; PKCS#12 or JKS keystores; text files; binary files). Variables can be literals or Kubernetes references (secretKeyRef, configMapKeyRef, fieldRef, resourceFieldRef); files can come from inline content, ConfigMaps, Secrets, cert-manager Certificates, the Secrets Store CSI driver or image volumes.
What does docuconf generate from a contract?
Today: the contract in CUE and JSON, a validation report (docuconf vet), the pod’s env, volumes, mounts, ConfigMaps and injector annotations (docuconf render), a Helm values.schema.json plus a library chart, generated docs for developers and AI agents (docuconf docs), and the SDK’s boot-time violation report. Specified next: an OCI artifact tied to the image digest, a compatibility report (docuconf diff) and a Crossplane composition function. Planned: Knative, Kubernetes OpenAPI, admission policy, KCL and .env.example targets.
What must a docuconf language SDK support?
It must extend the language’s leading config library rather than replace it, cover every type and field, validate the declaration itself, export a deterministic contract with the encodings its host parses, load from the process environment, report every violation at boot with stable error codes without printing secrets, check every file input (including TLS key match and expiry), honour reload: watch or reject it, support DOCUCONF_FILE_ROOT and pass the shared conformance suite.
Which languages have docuconf SDKs?
Go, TypeScript, .NET, Python, Ruby, Java, Kotlin, Rust, Swift, Elixir, Gleam, C++, PHP and COBOL. Each builds on that ecosystem’s leading library, for example caarlos0/env in Go, T3 Env in TypeScript, the Options pattern in .NET, pydantic-settings in Python, Spring Boot configuration properties in Java, CLI11 in C++, and Laravel or Symfony configuration in PHP. In COBOL the declaration is an annotated copybook.
How does docuconf handle secrets?
A secret variable must be supplied as a secretKeyRef and a secret file from a Secret, cert-manager Certificate or CSI volume — never a literal or ConfigMap. The platform checks the reference; the SDK checks the content at boot. No tool ever prints a secret value.
Does docuconf work with Bank-Vaults, Vault Agent or other secret injectors?
Yes. SDKs validate the process environment when the app starts, after any injector has run, so a value from Bank-Vaults, a wrapper such as op run, or a mounted secret is checked like any other. On the platform side a variable can be declared as injected, with the injector’s reference (such as vault:secret/data/db#url), so validation accepts the reference instead of demanding a Kubernetes secretKeyRef.
Can the platform mount an appsettings.Production.json instead of setting environment variables?
Yes, as an overlay. The contract declares the overlay’s path and format; the platform writes the values at each variable’s config key into that file, in a ConfigMap, and the app layers it between its baked-in appsettings files and environment variables. Overlays apply to hosts that layer config files: .NET, Spring Boot, Rails, figment and Hoplite.
Is docuconf a feature-flag system?
No. docuconf covers configuration that changes only with a rollout. Flags that change at runtime per user or request belong in OpenFeature; only the flag provider’s bootstrap settings belong in the contract.