Extend value_mappings to support expr values

[amc-corey-cox]

Summary

Extend value_mappings so that mapping values can be expressions, not just literals. This keeps value_mappings as the single declarative lookup mechanism while supporting cases where each branch needs computed output.

Current behavior

value_mappings maps literal keys to literal values:

slot_derivations:
  visit_label:
    populated_from: visit_code
    value_mappings:
      "1": "SCREENING"
      "7": "BASELINE"

Proposed behavior

Mapping values can be either a literal string (unchanged) or an object with an expr field:

slot_derivations:
  visit_id:
    populated_from: visit_code
    value_mappings:
      "1":
        expr: "uuid5({id} + 'SCREENING')"
      "7":
        expr: "uuid5({id} + 'BASELINE')"

Motivation

When each branch of a value mapping needs different computation (not just a different literal), users currently have to inline everything into a case() expression, which is unreadable for non-trivial mappings. This extension keeps the mapping table as a clean, auditable artifact while allowing computed results.

Design decisions

• Literal string values continue to work unchanged — no migration needed
• The expr in a mapping value has access to the same bindings as a top-level expr (source fields, joins, etc.)
• No-match behavior: returns None (unchanged from current value_mappings)
• This subsumes the unimplemented expression_to_value_mappings field, which should be removed from the spec

Related

• Supersedes Support value_mappings as input to expr (mapping-then-expression pipeline) #160 (original proposal used mapped() function and pipeline pattern — this is simpler)
• Support derived slot bindings and hide for intermediate computations #164 — hide + slot() for cascading multi-stage patterns where the mapping result feeds into another expression
• Implement expression_to_expression_mappings in transformer runtime #127 — expression_to_expression_mappings discussion (concluded: use case() instead)

[github-actions]

Issue Summary

Type: Enhancement — spec extension + runtime implementation
Author: @amc-corey-cox
Status: Open, no PR yet
Priority context: Part of a coordinated 1.0 spec cleanup cluster

---

What this proposes

Extend value_mappings so that each mapping value can be either a literal string (current behavior, unchanged) or an object with an expr field (new):

slot_derivations:
  visit_id:
    populated_from: visit_code
    value_mappings:
      "1":
        expr: "uuid5({id} + 'SCREENING')"
      "7":
        expr: "uuid5({id} + 'BASELINE')"

The expr has access to the same bindings as a top-level expr (source fields, joins, etc.). No-match behavior is unchanged: returns None.

---

Why this exists (design history)

This issue is the final, refined design from a three-issue arc driven by real-world BioData Catalyst / FHS harmonization work:

Issue	Title	Status	Relationship
#127	Implement expression_to_expression_mappings	Open	Concluded: remove expression_to_expression_mappings and expression_to_value_mappings from spec; use case() instead. The expression_to_value_mappings use case is subsumed by this issue.
#160	value_mappings as input to expr (pipeline pattern)	Closed (superseded by this)	Original proposal used mapped() function. Rejected: mapped() has no compelling use case; the pipeline pattern is better served by #164. The core need — expr values in value_mappings — is this issue.
#164	hide + slot() for intermediate computations	Open	Complementary: enables multi-stage cascading patterns (map two fields independently, then combine). Depends on this issue landing first.

The root motivation: when visit codes need to be mapped to string labels and then fed into UUID generation, current options are (a) inline case() in expr — unreadable for large lookup tables — or (b) throwaway intermediate slot — pollutes output. This issue's approach keeps the lookup table as a clean, auditable YAML artifact.

---

Design decisions captured in this issue

1. Backward compatible — literal string values continue to work unchanged, no migration needed
2. Subsumes expression_to_value_mappings — that field (literal key → expression result) should be removed from the spec; this handles the same case more cleanly
3. No mapped() function — the earlier mapped() function proposal (Support value_mappings as input to expr (mapping-then-expression pipeline) #160) is dropped; the pipeline use case it addressed is better handled by hide + slot() (Support derived slot bindings and hide for intermediate computations #164)
4. Scope: not expression_to_expression_mappings (condition expression → result expression) — that's superseded by case() with and/or

---

Implementation notes

• Schema: value_mappings values currently typed as string. Will need to become a union type: string | { expr: string }. This touches transformer_model.yaml and the generated Pydantic models.
• Runtime: object_transformer.py, populated_from branch (~lines 318–347). After looking up the key, check if value is a string (return as-is) or an expr object (evaluate with current bindings).
• Related field to remove: expression_to_value_mappings on ElementDerivation / SlotDerivation — flag for removal before 1.0.
• SQL compiler (#150): would eventually need corresponding support for value_mappings with expr values.

---

Suggested next step

@dragon-ai-agent please implement the value_mappingsexpr-value extension described in issue #165. Specifically: (1) update the transformer model schema/pydantic to allowvalue_mappingsvalues to be either a literal string or an object with anexprfield, (2) updateobject_transformer.pyto detect which form is used and evaluate theexpragainst current bindings when present, (3) add scaffold-based tests followingtests/README.md, (4) mark expression_to_value_mappings as deprecated/unused in a comment (do not remove it yet — that's a separate PR). No-match behavior is unchanged (returns None).