Update documentation for recent features before RC

[amc-corey-cox]

Summary

Several recently landed and in-flight features lack user-facing documentation. This should be addressed before the release candidate.

Missing documentation for landed features

• -O/--additional-output multi-output CLI option (Add multi-output stream writers and -O CLI option #115) — not documented outside CLI --help. Needs usage examples and explanation of simultaneous multi-format output.
• uuid5() function (Add uuid5() function to transformation expressions #117) — not listed in docs/api/functions.md (which is currently a ~5-line stub). Needs examples showing deterministic ID generation.
• Multiple class_derivations for same target class (Allow multiple class_derivations for the same target class #118) — no examples or explanation of merging behavior. Needs YAML example and use-case guidance.
• simpleeval expression engine (Replace hand-rolled expression evaluator with simpleeval #122) — good docstrings in eval_utils.py, but no user-facing expression language guide. Related: Document unrestricted_eval and complex expression support #121.

Documentation needed for in-flight PRs

• Cross-table lookup / joins (Add cross-table lookup support for join-based transformations #136) — docs/schema/joins.md still says "not yet implemented". Needs usage guide with dot-notation lookup examples and source_schema_patches integration.
• Numeric string coercion in comparisons (Coerce numeric strings in comparison operators #135) — coercion behavior should be mentioned in expression language docs.

Stale docs

• docs/api/functions.md — nearly empty, doesn't list any available functions
• docs/schema/joins.md — says "not yet implemented"

Suggested deliverables

1. Expression language guide (docs/api/expressions.md or expand docs/api/functions.md) — document available functions (uuid5, strlen, case, max, min, round, etc.), {slot} null-propagation, collection distribution, and numeric coercion rules
2. Multi-output docs — add -O usage examples to docs/index.md or a dedicated section
3. Update docs/schema/joins.md — remove "not yet implemented", add cross-table lookup examples
4. Multiple class_derivation examples — add to index or tutorial
5. Update mkdocs.yml nav if new pages are added

[github-actions]

Summary

This is a documentation tracking issue for features that landed (or are in-flight) ahead of the release candidate. Below is a status snapshot of all referenced issues/PRs.

---

Landed features needing docs (all PRs merged)

Feature	PR	Merged	Status
-O/--additional-output multi-output CLI	#115	2026-03-02	✅ Merged
uuid5() deterministic ID function	#117	2026-02-25	✅ Merged
Multiple class_derivations for same target class	#118	2026-02-25	✅ Merged
simpleeval expression engine	#122	2026-02-25	✅ Merged

#115 — Multi-output / -O flag: Adds StreamWriter ABC with JSON/JSONL/YAML/Tabular implementations and a MultiStreamWriter fan-out. The -O flag is repeatable and infers format from file extension. Needs usage examples in docs — e.g.:

linkml-map map-data -T spec.yaml -s schema.yaml -f jsonl -O /tmp/out.tsv -O /tmp/out.json input.tsv

#117 — uuid5(namespace, name): Generates deterministic UUIDs for cross-referencing between independently-processed specs. Namespace is a URL string (e.g. "https://w3id.org/bdchm/Visit"). Not listed in docs/api/functions.md (which is currently a stub).

#118 — Multiple class_derivations per target: Schema now uses inlined_as_list: true, so multiple derivations can target the same class (useful for fan-in from multiple source tables). Dict format preserved via backward-compat field_validator. No YAML examples in docs yet.

#122 — simpleeval engine: Replaces 270-line hand-rolled AST walker. Adds standard Python operators (!=, and/or/not, in, %, //, chained comparisons, is/is not) and new built-ins (int(), float(), bool(), abs(), round()). No user-facing expression language guide exists yet.

---

In-flight PRs (open, not yet merged)

Feature	PR/Issue	State
Cross-table lookup / joins (DuckDB)	#136	🟡 Open PR
Numeric string coercion in comparisons	#135	🟡 Open PR

#136 — Cross-table joins: Adds DuckDB-backed LookupIndex and a transform_spec() engine. Enables join_on: / source_key: / lookup_key: in YAML specs and dot-notation lookups like {demographics.age_at_exam} in expressions. docs/schema/joins.md currently says "not yet implemented" and needs a full update.

#135 — Numeric string coercion: Fixes 1 == '1' returning False when TSV data is loaded (numeric fields become int/float but spec authors write string literals). Wraps six comparison operators in LinkMLEvaluator to auto-coerce. Needs mention in the expression language docs.

---

Related open issues

#121 — Document unrestricted_eval (OPEN): The transformer supports multi-statement expressions (list comprehensions, if/else, variable assignment) via unrestricted_eval=True, but this is completely undocumented, not exposed as a CLI flag, and multi_file_transformer.py silently hardcodes it to True. This is a sub-issue of #98 and closely related to the expression language guide deliverable here.

---

Stale docs that need updating

• docs/api/functions.md — ~5-line stub; doesn't list any available functions (uuid5, strlen, case, max, min, round, int, float, bool, abs, etc.)
• docs/schema/joins.md — says "not yet implemented"; needs to be rewritten once Add cross-table lookup support for join-based transformations #136 merges

---

Suggested doc deliverables (from issue)

1. Expression language guide (docs/api/expressions.md or expanded docs/api/functions.md) — cover all built-in functions, {slot} null-propagation, collection distribution, numeric coercion rules, and unrestricted_eval (see Document unrestricted_eval and complex expression support #121)
2. Multi-output docs — add -O usage examples to docs/index.md or a new CLI section
3. Update docs/schema/joins.md — rewrite once Add cross-table lookup support for join-based transformations #136 merges
4. Multiple class_derivations examples — add to tutorial/index
5. Update mkdocs.yml nav if new pages are added

[amc-corey-cox]

Related issues

Directly addressed by this documentation work:

• Document unrestricted_eval and complex expression support #121 — Document unrestricted_eval and complex expression support (expression language guide covers this)
• Housekeeping - documentation items to update #76 — Housekeeping documentation items to update (overlapping scope)

Features whose PRs need documentation (referenced in body):

• Support cross-table slot lookup in class_derivation slot_derivations #134 / PR Add cross-table lookup support for join-based transformations #136 — Cross-table slot lookup (joins docs)
• Expression evaluator should coerce types for numeric string comparisons #133 / PR Coerce numeric strings in comparison operators #135 — Numeric string coercion in comparisons (expression docs)

Expression language and functions:

• identify expression language and implementation(s) in LinkML. Applicable to linkml-map? #98 — Identify expression language and implementation(s) in LinkML (expression guide addresses this)
• Implement expression_to_expression_mappings in transformer runtime #127 — Implement expression_to_expression_mappings (docs should note current status)

Schema and class derivation:

• Deprecate object_derivations in favor of list-based class_derivations #112 — Deprecate object_derivations in favor of list-based class_derivations (multiple class_derivations docs should reference this)
• Test: slot import with range override (MIxS string → structured object) #129 — Slot import with range override / Schema-Automator any_of (docs on source_schema_patches and validation fixes)

Release:

• Could we cut a release with the vulnerability fixes from PR #119 #123 — Cut a release with vulnerability fixes (this docs work is part of RC readiness)

[amc-corey-cox]

Closed by #154 — all documentation items addressed for RC.