Schema Authoring

Schemas tell decoct what a platform’s default values are, which fields are noise, and which fields are system-managed. This guide covers writing custom schemas, using LLM-assisted generation, and contributing schemas upstream.

Schema File Format

platform: my-platform
source: vendor documentation v2.1
confidence: authoritative
defaults:
  settings.timeout: 30
  settings.retries: 3
  services.*.enabled: true
drop_patterns:
  - "**.uuid"
  - "**.generated_id"
system_managed:
  - "**.creationTimestamp"
  - "**.lastModified"

Required Fields

Field	Description
`platform`	Platform identifier (e.g. `docker-compose`, `kubernetes`). Used for display and as the bundled schema short name.
`source`	Where the defaults came from. Cite the specification version or documentation URL.
`confidence`	One of `authoritative`, `high`, `medium`, `low`. Controls stripping aggressiveness.

Optional Fields

Field	Description
`defaults`	Map of dotted path patterns to default values. Values are compared with type coercion.
`drop_patterns`	Glob patterns for fields to unconditionally remove (UUIDs, hashes, etc.).
`system_managed`	Glob patterns for platform-generated fields (timestamps, internal IDs).

Path Pattern Syntax

Pattern	Matches
`services.web.image`	Exact path
`services.*.restart`	`*` matches one segment
`**.managedFields`	`**` matches any depth
`metadata.**.name`	`**` in the middle

Confidence Levels

Level	Meaning	Behaviour with `skip_low_confidence`
`authoritative`	From official specification	Always stripped
`high`	Verified against vendor docs	Always stripped
`medium`	Derived from examples	Skipped when `true`
`low`	Inferred or uncertain	Skipped when `true`

Using `decoct schema learn`

The schema learn command uses Claude to extract defaults from example configs and/or documentation. Requires pip install decoct[llm] and ANTHROPIC_API_KEY.

# From example config files
decoct schema learn -e config1.yaml -e config2.yaml -p my-platform -o schema.yaml

# From vendor documentation
decoct schema learn -d vendor-docs.md -p my-platform -o schema.yaml

# From both
decoct schema learn -e config.yaml -d docs.md -o schema.yaml

Flag	Description
`-e`, `--example`	Example config file (repeatable)
`-d`, `--doc`	Documentation file (repeatable)
`-p`, `--platform`	Platform name hint
`-o`, `--output`	Output file path
`-m`, `--merge`	Merge into existing schema
`--model`	Anthropic model (default: `claude-sonnet-4-20250514`)

Always review generated schemas against official documentation before production use.

Merging Defaults

Merge newly discovered defaults into an existing schema:

decoct schema learn -e new-examples.yaml -m existing-schema.yaml -o merged.yaml

Existing entries are preserved; only new path/value pairs are added.

Testing Your Schema

# See what gets stripped
decoct compress config.yaml --schema my-schema.yaml --show-removed

# Check token savings
decoct compress config.yaml --schema my-schema.yaml --stats

# Compare compressed to original
decoct compress config.yaml --schema my-schema.yaml -o compressed.yaml
diff config.yaml compressed.yaml

Verify:

No important fields removed (check --show-removed)
Token savings in expected range (30-50% typical for platform-aware schemas)
Default values are accurate (wrong defaults silently remove user-configured values)

Example: Docker Compose Schema

platform: docker-compose
source: Docker Compose specification + compose-go source
confidence: authoritative
defaults:
  services.*.restart: "no"
  services.*.privileged: false
  services.*.read_only: false
  services.*.stdin_open: false
  services.*.tty: false
  services.*.init: false
  services.*.healthcheck.interval: 30s
  services.*.healthcheck.timeout: 30s
  services.*.healthcheck.retries: 3
  services.*.deploy.replicas: 1
  networks.*.driver: bridge
  networks.*.external: false

Example: Kubernetes Schema

platform: kubernetes
source: Kubernetes API Reference (v1.29+)
confidence: authoritative
defaults:
  "**.restartPolicy": Always
  "**.terminationGracePeriodSeconds": 30
  "**.containers.*.imagePullPolicy": IfNotPresent
  "**.containers.*.ports.*.protocol": TCP
  spec.replicas: 1
  spec.revisionHistoryLimit: 10
  spec.strategy.type: RollingUpdate
system_managed:
  - metadata.uid
  - metadata.resourceVersion
  - metadata.generation
  - metadata.creationTimestamp
  - metadata.managedFields
  - status

Contributing Schemas Upstream

To add a schema to the bundled set:

Schema file in src/decoct/schemas/bundled/<name>.yaml
Short name added to BUNDLED_SCHEMAS in resolver.py
source field cites a verifiable reference
Confidence is authoritative or high
All default values verified against platform documentation
Test fixture added in tests/fixtures/