YAML Configuration

Oridecon merges user-defined YAML files, environment variables, and code defaults into a single typed configuration object. This page covers the mechanics; for a task-oriented walkthrough see Configuration.

1. The Configuration File

The primary file is application.yaml in the project root. Core settings are top-level; each extension reads its own named section:

application.yaml

app_name: "order-service"
debug: false
env: "production"

sql:                                   # oridecon-sql (config_key: "sql")
  backend:
    url: "${DATABASE_URL:sqlite+aiosqlite:///./dev.db}"
  pool:
    min_size: 2
    max_size: 10

cache:                                 # oridecon-cache (config_key: "cache")
  backends:
    - name: redis
      type: redis
      default: true
      redis_url: "${REDIS_URL}"

Loading config

from oridecon import OrideconConfig

config = OrideconConfig.from_yaml()                          # ./application.yaml (CWD)
config = OrideconConfig.from_yaml("config/application.yaml")
config = OrideconConfig.from_env_profile()                   # recommended: same file, plus ORI_PROFILE

Relative paths resolve from the process CWD. A missing file is not an error — Oridecon logs config.defaults_only and uses code defaults. Both loaders overlay application.{profile}.yaml when ORI_PROFILE is set (or profile= is passed), then apply ORI_* env vars. Application() with no config calls from_env_profile().

---

2. Environment Interpolation

Oridecon resolves ${VAR} placeholders inside YAML values at load time:

• ${PORT} — resolves to the PORT env var; fails fast if unset.
• ${PORT:8080} — resolves to PORT, or 8080 if unset.

sql:
  backend:
    url: "${DATABASE_URL:sqlite+aiosqlite:///./dev.db}"

---

3. Environment-Variable Overrides

Beyond interpolation, any key can be overridden by an environment variable using the ORI_ prefix and double underscores (__) for nesting. This is the highest-priority source:

sql.backend.url   →  ORI_SQL__BACKEND__URL
web.server.port  →  ORI_WEB__SERVER__PORT
auth.secret_key  →  ORI_AUTH__SECRET_KEY

The prefix is stripped and the rest is lowercased; __ becomes nesting. List indexes are not special — ORI_FOO__0__BAR becomes a dict key "0", not foo[0].

ORI_WEB__SERVER__PORT=9000 oridecon run

---

4. Configuration Profiles

Override base settings per environment with profile files. Activate a profile with ORI_PROFILE:

ORI_PROFILE=production oridecon run

• Base: application.yaml
• Overlay: application.{profile}.yaml (e.g. application.production.yaml)

---

5. Precedence Rules

When resolving a key, Oridecon applies sources in this order (highest priority wins):

1. ORI_ environment variables — ORI_WEB__SERVER__PORT=9000 overrides everything
2. Profile YAML — values from application.{profile}.yaml
3. Base YAML — values from application.yaml
4. Code defaults — defined in each config model

---

6. Typed Sections and get_section()

OrideconConfig exposes typed top-level fields and resolves extension sections on demand:

config = OrideconConfig.from_yaml()

# Typed top-level
config.app_name         # "order-service"
config.debug            # False
config.environment      # Environment.PRODUCTION

# Extension sections — pass the config model to get a typed object back
db_config = config.get_section("sql", DatabaseConfig)

# Dotted paths
rag_config = config.get_section("ai_rag", RAGConfig)

# Existence check
config.has_section("web")   # True

Providers rarely call get_section() themselves — declaring config_key and config_model makes the framework inject the typed section automatically. See Configuration → auto-injection.

---

7. Profile Examples

application.development.yaml

debug: true
logging:
  level: DEBUG
  json_format: false
sql:
  backend:
    url: "sqlite+aiosqlite:///./dev.db"

application.production.yaml

debug: false
logging:
  level: WARNING
  json_format: true
cache:
  backends:
    - name: redis
      type: redis
      default: true
      redis_url: "${REDIS_URL}"

Inspect the resolved tree (secrets masked):

oridecon config show
oridecon config validate
oridecon config doctor --env production

---

Next Steps

• Configuration — the practical guide
• The oridecon CLI — config show, config doctor, config env
• Application Lifecycle — when config is loaded during boot
• Environment variables — generated ORI_* registry