Implement expression_to_expression_mappings in transformer runtime

[amc-corey-cox]

Summary

The expression_to_expression_mappings field is defined in the linkml-map schema (SlotDerivation class) but is not implemented in the transformer runtime. Files that use this field pass schema validation but the mappings are silently ignored during transformation.

Current behavior

When a SlotDerivation includes expression_to_expression_mappings, the transformer does not process them — the mappings have no effect on the output.

Expected behavior

The transformer should evaluate expression_to_expression_mappings entries, applying the source-to-target expression mapping during transformation.

Use case

We're writing transformation specs for the BioData Catalyst harmonized variables project where visit identifiers need to be mapped through expressions. Currently we use case() expressions as a workaround:

associated_visit:
  expr: 'uuid5("https://w3id.org/bdchm/Visit", str({phv00177237}) + ":" + case(({phv00177238} == ''2'', ''FHS NEW OFFSPRING SPOUSE EXAM 2''), ({phv00177238} == ''3'', ''FHS GENERATION 3 EXAM 2'')))'

With expression_to_expression_mappings support, this could be expressed more cleanly:

associated_visit:
  populated_from: phv00177238
  expression_to_expression_mappings:
    '{phv00177238} == 2': 'uuid5("https://w3id.org/bdchm/Visit", str({phv00177237}) + ":FHS NEW OFFSPRING SPOUSE EXAM 2")'
    '{phv00177238} == 3': 'uuid5("https://w3id.org/bdchm/Visit", str({phv00177237}) + ":FHS GENERATION 3 EXAM 2")'

Environment

• linkml-map version: 0.3.9
• The schema field exists in transformer_model.py as part of SlotDerivation

[github-actions]

Issue Summary

Reported by: @amc-corey-cox (BioData Catalyst harmonized variables project)

What's broken

expression_to_expression_mappings is defined in the schema (transformer_model.yaml, transformer_model.py, transformer_model_new.py) on SlotDerivation (and other derivation classes), but has zero implementation in the transformer runtime (object_transformer.py). The field silently does nothing — no error, no warning, no effect.

Related context

This follows the same pattern as issue #64 ("Allow lookup translation of values", closed June 2025), which resulted in the implementation of value_mappings. The current issue is the natural next step:

Field	Key type	Value type	Status
value_mappings	literal string	literal string	✅ Implemented (lines 318–320 in object_transformer.py)
expression_to_value_mappings	expression (evaluated)	literal string	❌ Not implemented
expression_to_expression_mappings	expression (evaluated)	expression (evaluated)	❌ Not implemented (this issue)

Current workaround

The reporter uses the case() function in an expr field, which works but is less readable for long multi-branch mappings.

What implementation would look like

The transformer already has eval_expr / eval_expr_with_mapping in linkml_map/utils/eval_utils.py. The needed logic would be added near the value_mappings block (around line 318 in object_transformer.py):

1. Iterate over entries in expression_to_expression_mappings
2. For each entry, evaluate the key as a boolean expression against the source object bindings
3. If the key evaluates truthy, evaluate the value expression to produce the output
4. Return the first matching result (first-match-wins semantics, consistent with case())

expression_to_value_mappings (key=expression, value=literal) should be implemented at the same time as it's essentially the same logic without the second eval step.

Scope

• object_transformer.py — add evaluation logic for both expression_to_value_mappings and expression_to_expression_mappings
• Tests in tests/test_transformer/ (scaffold-based pattern per tests/README.md)
• Docstring / YAML spec examples

@dragon-ai-agent please implement expression_to_expression_mappings(andexpression_to_value_mappings) in the transformer runtime (object_transformer.py). The key of each entry is a boolean expression evaluated against source bindings (first-match wins); for expression_to_expression_mappingsthe value is also an expression to evaluate; forexpression_to_value_mappingsthe value is a literal string. Add scaffold-based tests following the pattern intests/README.md. Use eval_expr/eval_expr_with_mappingfromlinkml_map/utils/eval_utils.py. Do not make any architectural changes beyond what is needed.

[amc-corey-cox]

Design discussion (2026-03-25)

After reviewing the spec surface for 1.0 readiness, we concluded:

Recommendation: remove expression_to_expression_mappings and expression_to_value_mappings from the spec

The three mapping mechanisms on ElementDerivation (value_mappings, expression_to_value_mappings, expression_to_expression_mappings) are confusing. Only value_mappings is implemented; the other two are dead fields.

The use case in this issue — conditional value construction based on field matching — is better served by:

1. Extending value_mappings to allow expression values (covers Support value_mappings as input to expr (mapping-then-expression pipeline) #160): literal key → expr result. This handles the common case of "look up a coded value, then use it in a computation."

2. Using case() expressions with and/or for genuinely complex conditional dispatch where the keys are also expressions. The and/or operators are now implemented, which should make the case() syntax significantly more readable than the workarounds that motivated this issue.

Why not implement expression_to_expression_mappings?

• It's an ordered list of condition→expression rules — fundamentally different from value_mappings (which is an O(1) dict lookup). Overloading the "mappings" concept obscures this.
• The expression language already supports this via case(). Adding a second way to express conditional logic increases spec surface without clear utility gain.
• If case() proves too painful after curators have and/or available, we can revisit with a dedicated conditional_mappings field — but we shouldn't ship it speculatively in 1.0.

Action items

• Remove expression_to_expression_mappings from the spec before 1.0
• Remove expression_to_value_mappings from the spec (subsumed by value_mappings + expr values, see Support value_mappings as input to expr (mapping-then-expression pipeline) #160)
• Extend value_mappings values to support expr (Support value_mappings as input to expr (mapping-then-expression pipeline) #160)
• Revisit if curators report case() is still painful after and/or adoption

[amc-corey-cox]

Closing as won't-fix. The design discussion on this issue (2026-03-25) concluded that expression_to_expression_mappings and expression_to_value_mappings should be removed from the spec before 1.0 rather than implemented:

• expression_to_value_mappings is subsumed by value_mappings with expr values (Extend value_mappings to support expr values #165, PR Support expr values in value_mappings #195)
• expression_to_expression_mappings is subsumed by case() with and/or operators

Both fields are now marked deprecated in the schema (PR #195). Removal will happen in a separate pre-1.0 PR.