Semantic validation

Syntactic / schema checks are not enough for agents. Use the structured validation API.

API

from drtoller.framework.capability import validate_manifest_path

result = validate_manifest_path("step.drtml", compile=True)
if not result.valid:
    for err in result.errors:
        print(err.code, err.path, err.available)

Also available via drtoller.framework.drtml.errors: ValidationIssue, SemanticValidationResult, DrtmlValidationError, raise_validation_error.

CLI

drtoller validate path/to/step.drtml --format json
drtoller validate path/to/step.drtml --compile --format json
drtoller plan path/to/step.drtml --format json

JSON shape: {valid, errors[{code, path, message, expected, received, available, fixes, details}]}.

Error shape

Field	Purpose
code	Stable machine code (UNKNOWN_EXECUTION_MODE, INCOMPATIBLE_INPUT, …)
path	Location in the manifest / composition
message	Human-readable text
expected / received	Types or values
available	Allowed alternatives when known
fixes	Deterministic repair hints when available
details	Extra structured context

DrtmlValidationError is a ValueError subclass — existing call sites that match message substrings keep working; agents should prefer structured fields.

All DRTML parse/validate hot paths raise through raise_validation_error (not bare ValueError). The same structured fields are emitted from compile, flush/checkpoint, feed, metrics, panels/UI, dispatch, mapping_mode, reduce_merge, and embed_train.mode_spec.

Stable codes (non-exhaustive)

Code	Typical use
MISSING_REQUIRED	Required field / section absent
INVALID_TYPE	Wrong YAML/JSON type
INVALID_ENUM	Value not in allowlist (available)
INVALID_VALUE	Semantic constraint failed
UNKNOWN_DATASET / UNKNOWN_COLUMN	Reference not in manifest
UNKNOWN_PATTERN / UNKNOWN_EXECUTION_MODE	Dispatch / run type
UNSUPPORTED_BACKEND / UNSUPPORTED_PARAM_NAMESPACE	Outside whitelist
FORBIDDEN_FIELD	Removed / illegal combination
INCOMPATIBLE_INPUT	Composition mismatch
INVALID_DRTML_VERSION	Version too old for pattern

See also the human-oriented Validation and compile page.