Errors

DataSchemer (DS) validates DataCanon Instances (DCIs), the values in DataCanon’s data model. A DataCanon Type (DCT) constraint requires a particular data type. Catch DSUserError at the application’s user-input boundary:

from data_schemer.errors import DSUserError

try:
    projection = projector.get_projection(input_dci)
except DSUserError as error:
    print(error.user_message())

The base class provides user_message() and a default exit_code of 2. SchemaCommandLine.main() prints caught DS user errors to stderr and returns their exit code. Calling the constructor directly allows the caller to handle exceptions itself.

DCT mismatch

DSInvalidTypeError records a field whose DCT differs from its declared constraint. For a nested Float supplied where Integer is required:

Invalid type for field "solver.iterations".
Expected: Integer
Received: Float
Value: 1.0

The exception exposes:

Paths describe the input data, independently of schema names and constructor aliases. A literal field name containing a dot uses bracket notation:

Invalid type for field ["solver.iterations"].

That path is ("solver.iterations",), distinct from the nested path above. Diagnostic summaries describe numerical arrays by dtype and shape, bound long values, and do not retrieve external payloads or invoke conventional conversion.

Array element-type mismatch

DSInvalidArrayTypeError reports an Array DCI that does not satisfy its field’s array_type constraint:

Invalid Array type for field "solver.matrix".
Expected: float64
Received: float32
Value: Array(type=float32, shape=(2, 2))

It is a subclass of DSInvalidTypeError and DSUserError, retaining path, expected, received, and value_summary. For this exception, expected and received name portable Array element types. Nested invalid defaults preserve the same exception class and data path. A non-Array value fails the DCT check first and raises the ordinary DSInvalidTypeError.

Other input errors

The unused legacy DSCoercionError and DSInvalidChoiceError classes have been removed. Failed field choices are reported through DSUserError.

Invalid configuration and required files

Malformed schema dictionaries, inheritance lists, field choices or dependencies, conflict groups, and attribute-output settings produce DSUserError diagnostics. SCL also reports invalid option metadata and conflicting aliases as DS user errors rather than exposing argparse construction errors.

required_file metadata is checked before file access. Its switches must be Booleans, read_mode must be path, text, or binary, and unknown metadata keys are rejected. Missing or unreadable files and invalid UTF-8 text produce user-facing messages. Path-only mode does not open or check a file’s contents.

Constructor and conversion failures

Missing constructor arguments, non-callables, and uninspectable callable signatures produce DSUserError during get_instance(). Signature binding runs before conventional conversion.

Once selected arguments are converted and application construction starts, conversion failures and application exceptions propagate. For example, a constructor’s own ValueError remains a ValueError. A successful DCI projection does not guarantee that an external resource can later be retrieved or that an application constructor will accept its conventional arguments.

Validation of schema and SCL metadata is separate from application execution. DS does not broadly wrap arbitrary implementation failures or exceptions from registered conventional conversion handlers into input errors.