Validate Plugin Configuration

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

What You Build

You will define a JSON-compatible component config, validate required fields and supported values, return structured diagnostics, and confirm that disabled components still report config 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.

Disabled components are still validated. This lets operators detect config problems before enabling a component in a later rollout.

1
from nemo_relay.plugin import ComponentSpec, ConfigPolicy, PluginConfig
2
3
config = 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

Validation should be deterministic and side-effect free. It should inspect config and return diagnostics; it should not register middleware, open network connections, create clients, or mutate process state.

Validate these areas first:

• Required fields are present.
• Field types match the supported shape.
• Unknown fields follow the configured policy.
• Known fields have supported values.
• 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.

1
import nemo_relay
2
3
report = nemo_relay.plugin.validate(config)
4
has_errors = any(diagnostic["level"] == "error" for diagnostic in report["diagnostics"])
5
if 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 fields under each supported policy.
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.

• Register runtime behavior with Register Plugin Behavior.
• Add rollout controls with Design Plugin Configuration.
• Review concrete validation patterns in Code Examples.