Multi-artifact emission: one source instance into multiple target containers

[amc-corey-cox]

Motivation

Some transformations need one source instance to emit artifacts into multiple target containers. Current class_derivations are one-to-one: a derivation emits one class instance per source match. Authors handle the one-to-many case by writing two separate derivations both rooted at the source class and walking the source twice — see docs/examples/MetamodelMapping.ipynb for the canonical workaround.

This works but couples the artifacts only by author convention, not by the spec model. The planner can't see that the two derivations operate on the same source instances, can't validate cross-references between the emitted artifacts, and can't optimize execution.

Concrete driver: schema-automator's EML importer (linkml/schema-automator#208). An EML <attribute> with an <enumeratedDomain> is the canonical origin of both a slot_definition (in the parent class's attributes map) and an enum_definition (in the schema-level enums map). This is the first concrete schema-to-schema use case driving the need; dm-bip and similar data-to-data consumers don't exercise it. Future XSD/JSON-Schema importers will hit the same pattern.

Proposed direction (strawman)

Allow a ClassDerivation to declare additional emitted artifacts beyond its primary class:

class_derivations:
  AttributeToSlot:
    populated_from: Attribute
    target_class: slot_definition
    publishes: { enum_name_for: self }
    slot_derivations: { ... }
    also_emit:
      - target_class: enum_definition
        when: "is_present(measurementScale.nominal.nonNumericDomain.enumeratedDomain)"
        place_into: "$target.enums"
        slot_derivations:
          name: { expr: "<naming expression>" }
          permissible_values: { ... }

The cross-reference between primary and secondary artifacts is declared via publishes / ref (proposed in #237) — the slot in the primary artifact and the enum in the secondary share a binding-keyed name.

Reversibility

also_emit doesn't change linkml-map's existing reversibility-where-lossless rule. The inverse engine needs to know which slot-and-enum pairs originated from the same source instance; when the cross-reference (#237) is explicit, that pairing is mechanical. Expression invertibility is inherited from the expressions themselves (a spec that uses slugify for naming is lossy regardless of also_emit; a spec that uses identity expressions remains reversible).

Rule: also_emit is reversible iff (a) the cross-reference binding is declared, and (b) the binding expression is invertible. This adds one rule and inherits the rest.

Open questions

• place_into surface. A dotted path into the target schema ("$target.enums") is explicit. Alternative: have the target slot in the trans-spec model carry container-selection semantics, so emission routes by target schema structure. The dotted path is simpler to start.
• Interaction with dictionary_key / cast_collection_as. How does emission into a map-keyed container interact with the secondary artifact's own keying? Likely the target slot's keying applies and the secondary artifact must include the key slot.
• Alternative: canonicalize two-walk pattern. If appetite for also_emit is low, the alternative is to elevate the MetamodelMapping.ipynb two-walk pattern as the documented idiom and add tooling (validation, cross-ref declarations) around it. also_emit makes the relationship first-class; convention is the other option.

References / contrasts

• Proposal: parent-context class derivations for flat-to-nested mappings #216 — parent-context (one source → one nested target; distinct from one source → multiple containers)
• Support multi-source class derivations via sources, slot-level sources, and _source_class binding #193 — multi-source class derivations (sources; fanning across enumerated source classes, opposite direction)
• Implement multi-row aggregation, group-by, and collection membership (in) operator #188 — multi-row aggregation (row reduction, not multi-emit)
• docs/examples/MetamodelMapping.ipynb — current canonical workaround
• Cross-class reference resolution between derived artifacts #237 — needed to make also_emit reversible and to validate pairings
• populated_from_descendants: iterate source instances regardless of containment path #236 — composable with also_emit (a fan-in derivation could itself use also_emit)

[github-actions]

Summary

Status: Open proposal — no implementation yet. Filed 2026-05-14 by @amc-corey-cox as part of a same-day cluster of three interrelated proposals (#236, #237, #239) all driven by the schema-automator EML importer (schema-automator#208).

---

The Problem

Current class_derivations are one-to-one: one source instance → one target artifact. When a single source instance must populate multiple distinct target containers (e.g., both a slot_definition in a class's attributes map and an enum_definition in the schema-level enums map), authors today write two separate derivations both rooted at the same source class and walk the source twice.

The canonical workaround is documented in docs/examples/MetamodelMapping.ipynb. It works but:

• Couples artifacts only by author convention, not by the spec model
• The planner cannot see that the two derivations operate on the same source instances
• Cross-references between emitted artifacts cannot be validated
• Execution cannot be optimized

Concrete driver: In EML (Ecological Metadata Language), an <attribute> with an <enumeratedDomain> is the canonical origin of both a slot_definition (in the parent class's attributes map) and an enum_definition (in the schema-level enums map). Future XSD/JSON-Schema importers will hit the same pattern.

---

Proposed Solution: also_emit

Allow a ClassDerivation to declare additional emitted artifacts beyond its primary class:

class_derivations:
  AttributeToSlot:
    populated_from: Attribute
    target_class: slot_definition
    publishes: { enum_name_for: self }      # cross-ref binding (see #237)
    slot_derivations: { ... }
    also_emit:
      - target_class: enum_definition
        when: "is_present(measurementScale.nominal.nonNumericDomain.enumeratedDomain)"
        place_into: "$target.enums"
        slot_derivations:
          name: { expr: "<naming expression>" }
          permissible_values: { ... }

Cross-references between primary and secondary artifacts are declared via publishes / ref (proposed in #237).

Reversibility rule: also_emit is reversible iff (a) the cross-reference binding is declared, and (b) the binding expression is invertible. Inherits all other existing reversibility rules unchanged.

---

Open Design Questions

Question	Options	Current lean
place_into surface	Dotted path "$target.enums" vs. container-selection by target schema structure	Dotted path — simpler to start
Interaction with dictionary_key / cast_collection_as	Secondary artifact must include the key slot	TBD
Alternative: don't add also_emit	Elevate the two-walk pattern as documented idiom + add validation/cross-ref tooling around it	Option left open

---

Related Issues

Issue	Title	Status	Relationship
#237	Cross-class reference resolution (publishes/ref)	Open	Required for also_emit reversibility and pairing validation — filed same day
#236	populated_from_descendants: iterate source instances regardless of containment path	Open	Composable with also_emit — a descendant derivation could itself use also_emit; shares same DuckDB scratch-store execution model
#216	Parent-context class derivations (populated_from_parent) for flat-to-nested mappings	Open	Contrast — one source → one nested target (different direction); not a dependency
#193	Multi-source class derivations via sources	Open	Contrast — many source classes → one derivation (fan-in, opposite direction to also_emit's fan-out)
#188	Multi-row aggregation, group-by, in operator	Open	Orthogonal — row reduction, not multi-artifact emission
schema-automator#208	EML importer	Open	Concrete driver — the EML <attribute> → slot_definition + enum_definition pattern is the primary motivating use case

---

Architectural Context

Issues #236, #237, and #239 form a coordinated cluster filed together on 2026-05-14, all motivated by the EML importer work. They share a common execution model vision: an opt-in DuckDB-backed scratch store with two-pass execution that unlocks:

• Descendant iteration (populated_from_descendants: iterate source instances regardless of containment path #236)
• Cross-derivation reference resolution (Cross-class reference resolution between derived artifacts #237)
• Multi-artifact emission with validated pairings (Multi-artifact emission: one source instance into multiple target containers #239)

Specs that declare none of these features remain single-pass and fully streamable. The DuckDB infrastructure is already a direction the project is investing in (SQL compiler, engine work referenced in #237).

also_emit is the "production" half of the cross-reference story — #237 (publishes/ref) is the "wiring" half. The two proposals are designed as a pair and would likely be implemented together.