Build PluginsLanguage Binding

Validate Plugin Configuration

View as Markdown

Use this guide when you have a plugin kind and need predictable diagnostics before the plugin installs runtime behavior.

What You Build

Define a JSON-compatible component configuration, validate required fields and supported values, return structured diagnostics, and confirm that disabled components still report configuration problems before rollout.

Configuration Shape

The canonical plugin configuration is a top-level document with version, components, and policy.

Each component has:

  • kind: the plugin kind to activate.
  • enabled: whether the component should initialize.
  • config: the component-local JSON object passed to validation and registration.

Relay validates disabled components. This lets operators detect configuration problems before enabling a component in a later rollout.

The top-level policy controls validation that Relay handles, including unknown plugin kinds and unsupported document versions. A custom plugin’s validate() method controls how its own config fields handle unknown fields and unsupported values.

The following examples create the same configuration in each supported binding:

1from nemo_relay.plugin import ComponentSpec, ConfigPolicy, PluginConfig
2
3config = PluginConfig(
4    version=1,
5    components=[
6        ComponentSpec(
7            kind="header-plugin",
8            enabled=True,
9            config={"header_name": "x-tenant", "value": "tenant-a"},
10        )
11    ],
12    policy=ConfigPolicy(
13        unknown_component="warn",
14        unknown_field="warn",
15        unsupported_value="error",
16    ),
17)

Validation Rules

Keep validation deterministic and side-effect free. Inspect configuration and return diagnostics. Do not register middleware, open network connections, create clients, or change process state.

Validate these areas first:

  • Required fields are present.
  • Field types match the supported shape.
  • Your plugin reports unknown component-local fields with the diagnostic level its contract defines.
  • Your plugin reports unsupported component-local values with the diagnostic level its contract defines.
  • Cross-field combinations make sense.
  • Sensitive values are references or secret names, not raw credentials.

Use warnings when a config can still activate but deserves operator attention. Use errors when initialization should not proceed.

Diagnostic Shape

Diagnostics should be actionable and stable enough for tests or deployment automation:

1[
2  {
3    "level": "error",
4    "code": "header-plugin.missing_header_name",
5    "component": "header-plugin",
6    "field": "header_name",
7    "message": "config.header_name is required"
8  }
9]

Prefer stable diagnostic codes over prose-only messages. The message can improve over time; the code should remain testable.

Validate Before Initialization

Use the validation API before initialization and fail deployment if the report contains errors.

This error check does not catch an enabled unknown or unregistered component kind. Under the default unknown_component="warn" policy that case is reported as a warning, not an error, so the check below passes while initialize() still raises for an enabled kind that is not registered. Register every enabled kind before initialization, or set unknown_component="error" to make validation fail on unknown kinds.

validate() checks only the configuration you pass to it. initialize() also layers discovered plugins.toml configuration. A preflight report can pass while the effective startup configuration activates or rejects other components. Refer to Plugin Configuration Files when file discovery participates in deployment.

Append the following validation step to the matching configuration example above. Each example stops deployment when validation reports an error:

1import nemo_relay
2
3report = nemo_relay.plugin.validate(config)
4has_errors = any(diagnostic["level"] == "error" for diagnostic in report["diagnostics"])
5if has_errors:
6    raise RuntimeError(report["diagnostics"])

Validation Checklist

Before sharing a plugin config contract:

  1. Validate the smallest correct config.
  2. Validate a config with each required field missing.
  3. Validate unsupported enum or mode values.
  4. Validate unknown component-local fields and their diagnostic levels.
  5. Validate disabled components with invalid config.
  6. Confirm diagnostics identify the component and field that needs action.

Common Issues

Check these symptoms first when the workflow does not behave as expected.

  • Config contains callables or client objects: Keep config JSON-compatible and instantiate objects inside plugin code.
  • Disabled components skip validation: Disabled components should still report config problems.
  • Diagnostics are hard to automate: Add stable codes and field names.
  • Validation opens network connections: Move runtime setup into plugin registration.

Next Steps

Use these links to continue from this workflow into the next related task.