Ruleset Configuration

SML files define features, rules, and effects. A ruleset can also include YAML configuration for behavior that sits outside the SML execution graph, such as declaring labels or choosing what the UI displays.

Configuration doesn’t create SML variables and can’t replace rule logic. Engine and worker components read each configuration section for their own purposes.

File layout

A directory-backed ruleset needs at least one configuration source: config.yaml at the ruleset root or a file with a lowercase .yaml extension directly inside a directory named config. Osprey scans every directory named config in the ruleset tree and loads the .yaml files immediately inside it. Keep exactly one config/ directory at the root to make file discovery predictable.

my-rules/
|-- main.sml
|-- config.yaml
|-- config/
|   |-- labels.yaml
|   `-- ui_config.yaml
|-- models/
`-- rules/

Use {} in config.yaml when the ruleset has no settings. Don’t leave a discovered configuration file empty: if any file is empty, Osprey treats the entire merged configuration as empty, and publishing the ruleset can fail.

Osprey deep-merges the files into one configuration object. Mappings combine and lists concatenate. Defining the same scalar key in more than one file causes ruleset loading to fail, even when the values match. Keeping each top-level section in one file avoids surprising merges.

Configuration sections

Each top-level YAML key is a configuration section. Osprey registers a schema for every section it understands, then checks the merged configuration alongside SML source validation and before execution graph compilation. Unsupported sections and invalid values prevent the ruleset from activating.

For example, the demo ruleset declares the meow label used by its SML rules:

labels:
  meow:
    valid_for: [User]
    connotation: positive
    description: testing label

This configuration lets Osprey:

• reject a rule that uses an undeclared label or applies it to the wrong entity type
• show the label’s description and connotation in the UI
• give LabelAdd, LabelRemove, and HasLabel a shared label definition

Other sections configure worker or UI behavior. For example, ui_config selects default summary features and external links. The available sections depend on the worker build in your deployment; a top-level key is valid only when that worker has registered it.

Applying updates

Configuration is versioned with its SML sources and contributes to the ruleset hash. When a source provider delivers an updated ruleset, Osprey validates the YAML and SML, then compiles the execution graph before activating it. If validation or compilation fails, the update doesn’t go live.

A directory-backed worker reads the ruleset at startup; it doesn’t watch files for changes. Use osprey-cli push-rules when your deployment accepts pushed rules.

See Examples for a complete ruleset that uses config/labels.yaml alongside SML rules.