Skip to main content
canonic.yaml is validated against CanonicConfig at load time. Unknown top-level fields are ignored rather than rejected. Only version and project are required: everything else defaults.

​
Top-level fields

FieldTypeDefaultGoverns
versionintn/a (required)Config schema version; currently only 1 is recognized.
projectProjectConfign/a (required)Project name and optional default_connection.
connectionslist[Connection][]Configured data sources; see Connectors.
llmLLMConfig | nullnullLLM provider config; see Configuring an LLM.
embeddingsEmbeddingConfigmodel: all-MiniLM-L6-v2Local embedding model for knowledge vector search.
telemetryTelemetryConfigenabled: falseOpt-in telemetry flag; see Instrumentation & evaluation.
reconcileReconcileConfigpropose-onlyAuto-apply policy for ingestion; see Ingestion & reconciliation.
runtimeRuntimeConfigair_gapped: falseAir-gapped enforcement; see LLM & embeddings runtime.
loggingLoggingConfiglevel: WARNING, format: textLog level, optional file, and text/json format.

​
connections[]

connections:
  - id: warehouse_pg
    type: postgres
    params: { host: localhost, port: 5432, database: analytics, schema: analytics }
    credentials_ref: env:CANONIC_PG_PASSWORD
    read_only_role: null
  • credentials_ref (and llm.api_key_ref) must be a reference, one of env:, keyring:, or file:, never a literal secret; config validation rejects a literal outright.
  • Postgres/Redshift connections additionally recognize schema/schemas (search path) and tables (glob patterns narrowing introspection), plus fetch_column_stats: true to merge zero-scan cardinality/null-ratio stats into the returned schema (a no-op on SQLite/DuckDB).

​
llm

llm:
  provider: anthropic       # openai_compatible | anthropic | openai | github_copilot
  base_url: null            # required only for openai_compatible
  model: claude-opus-4-8
  api_key_ref: env:ANTHROPIC_API_KEY
  tasks: { reconcile: claude-opus-4-8 }   # per-task overrides: draft, reconcile, extract
Each provider has a fixed credential requirement, enforced at load: openai_compatible requires base_url; openai/anthropic require api_key_ref; github_copilot forbids one (device-code auth, outside canonic.yaml).

​
reconcile

reconcile:
  auto_apply:
    enabled: false             # default: propose-only
    min_confidence: 0.95
    max_provenance: inferred   # never auto-apply over human_curated+
    never: [grain, joins, measures]
  strict_contradictions: false

​
runtime

runtime:
  air_gapped: false
  allow_cidrs: []   # explicit private/LAN ranges for an on-prem inference host
When air_gapped: true, load-time validation additionally rejects: a public llm.base_url, telemetry.enabled: true, and any credentials_ref/api_key_ref using a non-local scheme.

​
Reserved directories

Independent of canonic.yaml fields, every project scaffolds four committed context directories (semantics/, knowledge/, contracts/, raw-sources/) plus a git-ignored .canonic/ local-state directory (created with 0o700 permissions).