YAML Schema Reference¶

The company template YAML describes a synthetic organisation: its agents, departments, budget, integrations, and operational policies. The schema is enforced by Pydantic models under src/synthorg/config/schema.py; this document captures the field set as a fixed-state reference. For the broader configuration precedence story (DB > env > code default) see docs/reference/configuration-precedence.md.

Top-level shape¶

company_name: Acme Robotics
company_type: startup
config:
  ...
agents:
  - name: ...
departments:
  - name: ...
budget:
  ...
integrations:
  ...
notifications:
  ...
security:
  ...
ontology:
  ...

Every top-level key is optional except company_name. Missing sections fall back to the Pydantic-defined defaults. Each agent declares a department by name, but the schema does not cross-check it against a declared departments[].name entry at load time.

RootConfig is extra="forbid", so an unrecognised top-level key fails config load rather than being silently ignored. This page documents the sections an operator sets directly (above, plus audit_chain at root); the schema carries roughly forty further top-level blocks with sensible defaults, covering engine internals (routing, capability policy, coordination, strategy detection, task engine, recovery, evolution), infrastructure (persistence, memory, api, sandboxing, mcp, queue, backup), and tool sub-configs (web, database, terminal, design, communication, analytics). Read src/synthorg/config/schema.py::RootConfig for the complete, current field list.

company_name / company_type¶

Company-wide runtime settings (autonomy, default budget, communication pattern, tool access) live under the top-level config: block, typed as CompanyConfig in src/synthorg/config/schema.py. The dashboard locale is not privileged towards any region: it resolves from the browser locale, falling back to the neutral en tag only when that is unavailable; see docs/reference/regional-defaults.md.

agents¶

A list of agent definitions; each must declare at least name, role, and department. The agent id is derived deterministically from name and is not authored by hand.

Every LLM dispatch names an explicit (provider, model) pair; for an agent that pair lives inside model and nowhere else. model carries provider and model_id directly, there is no separate per-agent provider field and no default-provider auto-pick to fall back on. A routing: block still exists (strategy name, ordered routing rules, fallback chain) but does not substitute for a per-agent binding.

departments¶

budget¶

This is the commonly-set subset; BudgetConfig (src/synthorg/budget/config.py) also carries per-model forecast priors, session token ceilings, per-provider subscriptions (quota tracking), and call-analytics knobs. See docs/guides/budget.md for the broader operations guide.

integrations¶

integrations is a fixed set of typed sub-blocks (the model is extra="forbid"):

integrations:
  enabled: true
  connections:
    max_connections_per_type: 100
  webhooks:
    replay_window_seconds: 300

There is no integrations.webhooks.enabled toggle: signature verification runs unconditionally on every delivery, so no switch exists to turn it off. Because the block is extra="forbid", writing one is not merely ignored: it fails config validation.

Individual connections (GitHub, Slack, SMTP, database, generic HTTP, OAuth apps) are not declared in YAML: they are created at runtime through the integrations API and their secrets live in the configured secret backend.

notifications¶

notifications:
  sinks:
    - type: slack
      enabled: true
      params:
        connection: ops-slack   # a bound SLACK connection holding the bot token
        channel: C0123456789
    - type: console
      enabled: true
  min_severity: warning

security¶

The hash-chained audit sink is a root-level block, not nested under security:

audit_chain:
  enabled: false   # opt-in; signs every audit event into the hash chain

Prompt-safety wrapping (wrap_untrusted) is always applied in code and has no YAML toggle; approval-timeout policy is configured under config.approval_timeout, not security.

ontology¶

User-defined entities live under ontology.entities.entries, not directly under ontology:

ontology:
  entities:
    entries:
      - name: cost_centre
        definition: ...
        fields:
          owner: the team accountable for spend against this centre
        constraints: [...]
        disambiguation: ...

ontology also carries backend ("sqlite", the only current option) and sub-blocks for context injection, drift detection, delegation guarding, memory integration, and org-memory sync. See docs/guides/ontology-extension.md for the entity-extension workflow.

Validation¶

The loader applies the Pydantic schema, then runs validation hooks including uniqueness checks (agent names, department names), a queue/message-bus dependency (queue.enabled requires backend == NATS with a non-null nats sub-block, since the distributed queue publishes claims through the JetStream client), and routing-reference checks (a routing rule, fallback, or fallback-chain entry must name a model a provider actually declares).

Failures surface at startup with a typed ConfigValidationError and a line/column pointer into the YAML.

Ingestion, not a live template¶

The YAML is not a precedence tier and there is no reload command for it: load_config runs once, at process boot, against the file named by SYNTHORG_CONFIG_PATH (default company.yaml). Its contents seed a RootConfig that flows into domain tables (departments, agents, budget) on synthorg init; from then on, the operator changes those entities through the dashboard and REST API against the persisted rows, not by re-applying or reloading the YAML file. Runtime-mutable values such as budget.currency are governed by the settings precedence chain in configuration-precedence.md, independent of the YAML that first seeded them.