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
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. One cross-section dependency applies: defining agents makes departments required, since every agent's department is mandatory and must name a declared department (see Validation).

company_name / company_type¶

Company-wide runtime settings (autonomy, default budget, communication pattern, tool access) live under the top-level config: block. The dashboard locale defaults to en-GB per the regional-defaults rule; 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. Provider and model selection flow through the routing layer (routing: plus per-agent model: hints), not a per-agent provider field.

departments¶

budget¶

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:
    enabled: true
    replay_window_seconds: 300

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:
        webhook_url: ${SLACK_WEBHOOK}
    - 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¶

ontology:
  terms:
    - name: cost_centre
      description: ...
      examples: [...]

See docs/guides/ontology-extension.md for the term-extension workflow.

Validation¶

The loader applies the Pydantic schema, then runs validation hooks:

• Cross-section references (agents[].department must name a declared departments[].name).
• Allowlist enforcement (notifications.sinks[].type must be a supported sink adapter).

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

Reload semantics¶

Most fields are hot-reloadable via synthorg config reload-template. Exceptions:

• New agents require a worker pool restart (the runtime caches per-agent prompts).
• budget.currency change requires draining the cost tracker first; the runtime refuses the reload until the tracker is empty.