YAML configuration schema reference

This is the complete field-level reference for meridian-tools YAML configuration files. For usage guidance, see the configuration guide.

All configuration models use Pydantic extra="forbid" — any key not listed here will produce a validation error.

Top-level structure

project: ProjectConfig         # optional, has defaults
data: CsvDataConfig            # required
model_spec: ModelSpecConfig    # optional, has defaults
fit: FitConfig                 # optional, has defaults
validation: ValidationConfig   # optional, has defaults
exports: ExportsConfig         # optional, has defaults
response_curves: ResponseCurvesConfig | null   # optional
optimisation: OptimisationConfig | null         # optional

`project`

Field	Type	Default	Description
`name`	`str`	`"meridian-project"`	Human-readable project name. Used as the base for run directory names.

`data`

Field	Type	Default	Description
`path`	`Path`	required	Path to CSV data file. Relative paths resolve against the YAML file’s directory.
`kpi_type`	`"revenue"` \| `"non-revenue"`	`"revenue"`	KPI type for Meridian’s data loader.
`coord_to_columns`	`dict[str, Any]`	required	Maps Meridian coordinate names to CSV column names. Must include `time`.
`media_to_channel`	`dict[str, str]` \| `null`	`null`	Optional media-to-channel mapping override.
`media_spend_to_channel`	`dict[str, str]` \| `null`	`null`	Optional media-spend-to-channel mapping override.
`reach_to_channel`	`dict[str, str]` \| `null`	`null`	Optional reach-to-channel mapping override.
`frequency_to_channel`	`dict[str, str]` \| `null`	`null`	Optional frequency-to-channel mapping override.
`rf_spend_to_channel`	`dict[str, str]` \| `null`	`null`	Optional RF-spend-to-channel mapping override.
`organic_reach_to_channel`	`dict[str, str]` \| `null`	`null`	Optional organic-reach-to-channel mapping override.
`organic_frequency_to_channel`	`dict[str, str]` \| `null`	`null`	Optional organic-frequency-to-channel mapping override.

`model_spec`

Field	Type	Default	Description
`kwargs`	`dict[str, Any]`	`{}`	Keyword arguments forwarded directly to Meridian `ModelSpec(**kwargs)`.
`priors`	`PriorsConfig` \| `null`	`null`	YAML-driven media prior configuration.

Supported kwargs keys include any argument accepted by Meridian’s ModelSpec constructor: max_lag, media_prior_type, holdout_id, etc. If holdout_id is present, the run is treated as an authored-holdout validation run.

Array-valued keys (holdout_id, control_population_scaling_id, non_media_population_scaling_id, rf_roi_calibration_period, roi_calibration_period) must be rectangular YAML lists of booleans. Scalars, ragged lists, string booleans such as "true", and numeric stand-ins such as 1/0 are rejected by the wrapper before Meridian model construction. Valid values are converted to NumPy arrays at runtime.

Authored holdout_id arrays are shape-checked after input data loading: national data expects (n_times,), and geo data expects (n_geos, n_times). Authored holdout_id cannot be combined with a runtime PipelineRunConfig.validation_spec.

Other wrapper-owned array kwargs are also rank- and shape-checked before model construction: roi_calibration_period expects (n_media_times, n_media_channels), rf_roi_calibration_period expects (n_media_times, n_rf_channels), control_population_scaling_id expects (n_controls,), and non_media_population_scaling_id expects (n_non_media_channels,). These kwargs require their corresponding data.coord_to_columns families to be authored.

`model_spec.priors`

Optional. If omitted, Meridian’s default PriorDistribution is used.

This focused YAML surface supports media prior parameters roi_m, mroi_m, and alpha_m.

Each prior parameter can be specified in scalar form:

model_spec:
  priors:
    roi_m:
      distribution: LogNormal
      loc: 0.2
      scale: 0.9

Or as a channel prior with a default distribution and per-channel overrides:

model_spec:
  priors:
    roi_m:
      default:
        distribution: LogNormal
        loc: 0.2
        scale: 0.9
      channels:
        paid_search:
          distribution: TruncatedNormal
          loc: 3.0
          scale: 1.5
          low: 0.0
          high: 6.0

Channel names in channels must match data.media_to_channel values. If no mapping is provided, they must match the raw media column names.

model_spec.priors and model_spec.kwargs.prior are mutually exclusive.

`DistributionSpec`

Field	Type	Description
`distribution`	`"Normal"` \| `"LogNormal"` \| `"TruncatedNormal"` \| `"Beta"`	Required distribution type.
`loc`	`float`	Required for `Normal`, `LogNormal`, and `TruncatedNormal`.
`scale`	`float`	Required and positive for `Normal`, `LogNormal`, and `TruncatedNormal`.
`low`	`float`	Required for `TruncatedNormal`.
`high`	`float`	Required for `TruncatedNormal`; must be greater than `low`.
`concentration0`	`float`	Required and positive for `Beta`.
`concentration1`	`float`	Required and positive for `Beta`.

`fit`

Field	Type	Default	Constraint	Description
`sample_prior_draws`	`PositiveInt` \| `null`	`null`	`>0` if set	Number of prior predictive draws. `null` skips prior sampling.
`n_chains`	`PositiveInt` \| `list[PositiveInt]`	`4`	`>0`	Number of MCMC chains.
`n_adapt`	`PositiveInt`	`500`	`>0`	Adaptation steps per chain.
`n_burnin`	`PositiveInt`	`500`	`>0`	Burn-in steps per chain.
`n_keep`	`PositiveInt`	`1000`	`>0`	Posterior samples to retain per chain.
`seed`	`int` \| `list[int]` \| `null`	`null`	—	RNG seed for reproducibility.
`max_tree_depth`	`PositiveInt`	`10`	`>0`	NUTS maximum tree depth.
`max_energy_diff`	`float`	`500.0`	—	NUTS maximum energy difference.
`unrolled_leapfrog_steps`	`PositiveInt`	`1`	`>0`	NUTS unrolled leapfrog steps.
`parallel_iterations`	`PositiveInt`	`10`	`>0`	TensorFlow parallel iterations.

`validation`

Field	Type	Default	Constraint	Description
`strategy`	`"none"` \| `"blocked_tail"` \| `"rolling_origin"`	`"none"`	—	Validation strategy.
`holdout_size`	`PositiveInt` \| `null`	`null`	Required for `blocked_tail`	Number of tail time periods to hold out.
`initial_train_size`	`PositiveInt` \| `null`	`null`	Required for `rolling_origin`	Initial training window size.
`test_size`	`PositiveInt` \| `null`	`null`	Required for `rolling_origin`	Test window size per split.
`step_size`	`PositiveInt` \| `null`	`null`	Must equal `test_size`	Step between rolling splits. Defaults to `test_size`.
`max_splits`	`PositiveInt` \| `null`	`null`	`>=2` if set	Maximum number of rolling splits.

Cross-field validation rules

strategy: none rejects all holdout and rolling-origin parameters.
strategy: blocked_tail requires holdout_size, rejects rolling-origin parameters.
strategy: rolling_origin requires initial_train_size and test_size, rejects holdout_size.
holdout_size without an explicit strategy is rejected (legacy shorthand removed).
Rolling-origin parameters without strategy: rolling_origin are rejected.

`exports`

Field	Type	Default	Description
`use_kpi`	`bool`	`false`	Use KPI-based metrics in Meridian analysis surfaces.
`batch_size`	`PositiveInt`	`1000`	Batch size for Meridian `Analyzer` computations.
`export_predictive_accuracy`	`bool`	`true`	Write `predictive_accuracy.csv`.
`export_review_summary`	`bool`	`true`	Write `review_summary.json`.
`export_model_selection`	`bool`	`true`	Write LOO/WAIC outputs (when compatible).
`export_plots`	`bool`	`true`	Write PNG plot artefacts in each stage.

`response_curves`

Optional section. If omitted or null, the response curves stage is skipped.

Field	Type	Default	Constraint	Description
`spend_multipliers`	`list[float]`	required	Non-empty, all `>=0`	Spend multiplier grid for response curve computation.
`use_posterior`	`bool`	`true`	—	Use posterior (vs prior) for response curves.
`by_reach`	`bool`	`true`	—	Compute reach-based response curves.
`use_optimal_frequency`	`bool`	`false`	—	Use optimal frequency in computation.
`confidence_level`	`float`	`0.9`	`0 < x < 1`	Confidence level for credible intervals.

`optimisation`

Optional section. If omitted or null, the optimisation stage is skipped.

Field	Type	Default	Constraint	Description
`start_date`	`str`	required	ISO `YYYY-MM-DD`	Start of the optimisation window.
`end_date`	`str`	required	ISO `YYYY-MM-DD`, `>= start_date`	End of the optimisation window.
`budget`	`OptimisationBudgetConfig`	required	—	Budget specification (see below).
`use_posterior`	`bool`	`true`	—	Use posterior (vs prior) for optimisation.
`use_optimal_frequency`	`bool`	`true`	—	Use optimal frequency in optimisation.
`confidence_level`	`float`	`0.9`	`0 < x < 1`	Confidence level for credible intervals.

`optimisation.budget`

Field	Type	Default	Constraint	Description
`mode`	`"fixed_total"` \| `"relative_reference_window_total"`	required	—	Budget mode.
`value`	`PositiveFloat`	required	`>0`	Budget value. Absolute for `fixed_total`, multiplier for `relative_reference_window_total`.

When mode: relative_reference_window_total, the effective budget is value × total_spend_in_reference_window. The reference window is defined by start_date and end_date.