Transform-time validation against target schema constraints

[amc-corey-cox]

Motivation

linkml-map's existing strict mode (f2363c3) catches one class of expression bugs: unbound names (typos, stale source references). Row-level errors during transformation already flow through TransformationError + the on_error callback path, with --continue-on-error toggling fail-fast vs collect-and-report at the CLI.

There's a category of error that falls outside both: the transform completed without exceptions, but the output is structurally invalid against the target schema. A trans-spec might:

• Leave a required: true slot empty because the source field was missing
• Produce a value for a slot with range: integer from a string-valued expression
• Emit multiple values into a singular slot, or a scalar into a multivalued one
• Produce an enum value not in the target enum's permissible values
• Build a class with no identifier when the target requires one
• Fail to populate a dictionary_key slot needed for map-keying
• Violate a pattern: declared on the target slot

Today these surface only after the fact via linkml-validate on the produced output. That works, but it loses source-instance provenance — by the time linkml-validate runs, the error reads "class X has no name" without telling you that the source Attribute with attributeName=' ' at row 47 of the input was the cause. For schema-construction trans-specs (importers like EML, XSD, JSON-Schema) source provenance is the most valuable piece of the diagnostic.

The collect-all-errors flow that the CLI already implements for row-level transformation errors is exactly the right ergonomics for these structural errors too: run the transform once, get all the malformed-input diagnostics in a single report, fix them in one pass.

Proposed direction

Extend transform-time validation to cover target-schema structural constraints, surfacing errors through the existing TransformationError + on_error infrastructure. Scope:

Cardinality / presence

• required: true slots evaluating to None
• identifier: true slots evaluating to None
• Slots used as dictionary_key evaluating to None
• Scalar slots getting list values
• multivalued: true slots getting non-iterable scalars

Type and range

• Range coercion failures (target range is integer, expression produced "abc")
• Range membership for typed ranges (date strings that don't parse, URIs that don't pattern-match)
• Enum membership: produced value not in the target enum's permissible values

Structural integrity

• Pattern violations on slots with pattern: declared
• Unresolved cross-references (when the cross-ref proposal in Cross-class reference resolution between derived artifacts #237 lands, a ref() consumer with no matching producer surfaces here)

Each violation builds a TransformationError populated with the class_derivation, slot_derivation, source row, and a discriminating kind field (or subclass) so consumers can filter. Errors flow through on_error when provided; otherwise they raise (fail-fast), matching the existing semantics. Non-strict mode produces output as-is with violations collected and reported at the end of the run.

Relationship to existing infrastructure

• TransformationError in transformer/errors.py — already carries the right shape (derivation names, source_row, row_index, cause). Add a kind: str field or small subclass hierarchy distinguishing required_missing, range_mismatch, cardinality_mismatch, enum_violation, pattern_violation, unresolved_reference.
• on_error callback in transformer/engine.py:59 — already the collect-vs-raise hook. No change needed; validation errors plug into the same path.
• --continue-on-error CLI flag at cli/cli.py:141 — already wired. Target-validation errors flow through the same path.
• --strict (f2363c3) — orthogonal: that one is about unbound names in expressions. The naming could become confusing as both grow; possibly rename one for clarity, or document the distinction prominently. See open questions.

Relationship to linkml-validate

This does not replace linkml-validate. The two layers compose:

• Transform-time validation: structural constraints native to the target schema, evaluated during emission, with source-instance provenance in each error. Covers the cases listed above.
• Post-transform linkml-validate: semantic / cross-record / dataset-level checks. Anything that depends on the whole output being assembled (uniqueness across records, inverse-slot consistency, complex constraint expressions).

The split is roughly: things you can know inside one derivation invocation → transform-time. Things that require the whole output → linkml-validate.

Reversibility implications

When inverting a trans-spec, the same validation infrastructure applies — the source schema becomes the target. One mechanism covers validation in both directions; no special-casing for reverse runs.

Open questions

• Validation cost. Running each derivation result through a meta-schema-driven check at emission time has measurable cost. Sample benchmarks before committing to default-on for all violation kinds; some (e.g., enum membership against a 10K-permissible-value enum) may want opt-in.
• --strict overload. linkml-map now has multiple notions of "strict": expression strict (f2363c3), and target-validation strict (this proposal). A single --strict flag toggling both is convenient but coarse. Consider per-area flags (--expression-strict, --validation-strict) with --strict as a meta-flag enabling all.
• Output shape on violation in non-strict mode. Two options for the emitted artifact: (a) emit the invalid value anyway (consistent with how runtime errors already behave under continue_on_error — output is as-the-trans-spec-produced-it, errors are advisory), or (b) emit a sentinel / skip the slot. Lean toward (a): predictable, debuggable, and matches existing semantics.
• Interaction with unrestricted_eval. No interaction expected; validation runs after expression evaluation regardless of eval mode.

References / contrasts

• f2363c3 — strict expression evaluation (unbound names); orthogonal but related vocabulary
• TransformationError in transformer/errors.py — the infrastructure this extends
• on_error callback in transformer/engine.py:59 — existing collect-vs-raise hook
• --continue-on-error in cli/cli.py:141 — existing CLI surface
• Cross-class reference resolution between derived artifacts #237 — cross-ref resolution; unresolved bindings are a violation kind covered here
• Multi-artifact emission: one source instance into multiple target containers #239 — multi-artifact emission; required-slot violations on secondary artifacts surface through this path
• Add slugify safe builtin for identifier-shaped expressions #242 — slugify returns None on unusable input; "must-not-be-None" enforcement for required slots lives here
• schema-automator's EML importer (EML (Ecological Metadata Language) importer schema-automator#208) — concrete consumer wanting transform-time provenance in errors

[github-actions]

Summary

Issue: Proposal to add transform-time structural validation against the target schema, surfacing errors with source-instance provenance through the existing error infrastructure.

---

Core Problem

A transformation can "succeed" (no exception thrown) but produce output that is structurally invalid against the target schema — e.g., a required: true slot left empty, a string emitted into an integer-ranged slot, or an enum value not in the permissible set. These failures currently only surface after the fact via linkml-validate, at which point the error message ("class X has no name") has lost the provenance link to the offending source row (e.g., Attribute.attributeName=' ' at row 47).

The proposal is to catch these violations at emit time, during the transform, so that each error carries the derivation name, source row, and row index — exactly what the existing TransformationError already supports.

---

Proposed Scope of Violations

Category	Examples
Cardinality / presence	required: true → None; identifier → None; dictionary_key slot → None; scalar slot gets list; multivalued slot gets scalar
Type / range	Range coercion failure (e.g., "abc" into integer); unparseable date/URI
Enum membership	Produced value not in permissible_values
Structural integrity	pattern: violation; unresolved ref() binding after #237 lands

---

Implementation Approach

Leverages existing infrastructure with minimal new surface:

• TransformationError (transformer/errors.py) — already carries derivation names, source row, cause. Proposed addition: a kind field discriminating required_missing, range_mismatch, cardinality_mismatch, enum_violation, pattern_violation, unresolved_reference.
• on_error callback (transformer/engine.py:59) — already the collect-vs-raise hook. No changes needed.
• --continue-on-error (cli/cli.py:141) — already wired. Validation errors flow through the same path automatically.

Non-strict mode emits the invalid value anyway (advisory errors, consistent with existing continue_on_error semantics). Strict mode raises on first violation.

---

Relationship to linkml-validate

This does not replace linkml-validate. The two compose:

• Transform-time: per-slot structural constraints, evaluated during emission, with source provenance. One-derivation-invocation scope.
• linkml-validate: semantic / cross-record / dataset-level checks (uniqueness, inverse-slot consistency, complex constraint expressions). Whole-output scope.

---

Open Questions

1. Performance: Some checks (enum membership against large permissible-value sets) may be expensive enough to want opt-in per-kind rather than default-on.
2. --strict naming collision: linkml-map now has two notions of "strict" — expression-strict (f2363c3, unbound names) and this validation-strict. A single --strict flag is convenient but coarse; consider --expression-strict / --validation-strict with --strict as a meta-flag.
3. Output shape on violation (non-strict mode): Emit invalid value (consistent, debuggable) vs. emit sentinel / skip slot. Proposal leans toward emitting as-is.
4. unrestricted_eval interaction: No interaction expected; validation runs after expression evaluation regardless.

---

Cluster Context

This issue is one of four coordinated proposals (all filed 2026-05-14, all open, all by @amc-corey-cox) driven by the schema-automator EML importer — a schema-as-source importer where source provenance in diagnostics is critical:

Issue	Title	Status	Relation to #241
#236	populated_from_descendants: iterate source instances across deep containment paths	Open	Shared DuckDB scratch-store execution model
#237	Cross-class reference resolution (publishes / ref)	Open	Unresolved ref() bindings become a violation kind covered here
#239	Multi-artifact emission (also_emit)	Open	Required-slot violations on secondary artifacts flow through this path
#241	Transform-time validation (this issue)	Open	—

The EML importer (schema-automator #208) is the concrete driver: an EML <attribute> with <enumeratedDomain> must derive both a slot_definition and an enum_definition, and the cross-reference between them (slot.range == enum.name) must be validated. All four proposals are needed together to make that importer implementable cleanly in linkml-map.

---

Implementation Order Suggestion

1. Cross-class reference resolution between derived artifacts #237 (cross-ref publishes/ref) — foundational; Multi-artifact emission: one source instance into multiple target containers #239 reversibility depends on it, Transform-time validation against target schema constraints #241 covers unresolved refs
2. Multi-artifact emission: one source instance into multiple target containers #239 (also_emit) — depends on Cross-class reference resolution between derived artifacts #237 for reversibility validation
3. Transform-time validation against target schema constraints #241 (this issue) — can start in parallel with Cross-class reference resolution between derived artifacts #237 for the cardinality/type/enum/pattern checks; unresolved-ref check waits on Cross-class reference resolution between derived artifacts #237
4. populated_from_descendants: iterate source instances regardless of containment path #236 (populated_from_descendants) — largely independent; can proceed in parallel

The cardinality, type, and enum/pattern validation in #241 can be implemented entirely without the other issues and would be immediately useful for single-artifact transforms.