Add --list-entities to validate-spec for external orchestration

[amc-corey-cox]

With #203, map-data -T <dir>/ --entity <name> lets external orchestrators (Make, snakemake, etc.) parallelize per-entity. The remaining gap is discovery — knowing which entities exist before planning the DAG.

A --list-entities flag on validate-spec --merge would close it:

linkml-map validate-spec --merge --list-entities -T specs/
# → one class_derivation name per line; skip schema-binding work

Pairs naturally with the existing --entity filter — same vocabulary. Thin wrapper over load_and_merge_specs: pull class_derivations, print sorted unique names, exit.

Context: dm-bip wraps load_and_merge_specs locally for now (linkml/dm-bip#323 → list_entities.py) and would delete it once this lands.

[github-actions]

Summary

This is the final piece of a three-part orchestration story:

Step	Issue/PR	Status
Design: multi-file loading, --entity, --emit-spec	#202	Closed (design doc)
Implementation of the above	#203	Merged 2026-05-06
Discovery: --list-entities for DAG planning	#243 (this)	Open

---

The Problem

After #203 landed, external orchestrators (Make, Snakemake, etc.) can parallelize per-entity:

linkml-map map-data -T specs/ --entity Person -s schema.yaml data/

But they can't discover which entities exist without running the full pipeline first. To build a DAG of parallel jobs, an orchestrator needs to enumerate the available class derivation names upfront.

The Proposed Fix

A --list-entities flag on validate-spec --merge:

linkml-map validate-spec --merge --list-entities -T specs/
# → one class_derivation name per line, sorted, then exit

This uses the same vocabulary as --entity (the class derivation name), making the two flags a natural pair: list → pick one → run.

Current Workaround (in dm-bip)

dm-bip PR #323 (branch retire-compose-specs-310) contains a local list_entities.py that wraps load_and_merge_specs directly. It would be deleted once this feature lands here.

---

Implementation Notes

This is a thin change — everything needed is already in place:

In cli.py:

• Add --list-entities as a flag option on validate-spec (same guard as --entity/--emit-spec: requires --merge)
• In _validate_spec_merged, after load_and_merge_specs returns, if flag is set: extract names, print sorted, exit early (skip schema binding and validation)

Name extraction from the merged dict's class_derivations:

• List format (list-of-blocks): each item is {"EntityName": {...}} — the single key is the name
• Dict format (standard): keys are the names

Both formats are already handled by the entity-filter logic in _validate_spec_merged (lines ~716–728), so the same pattern applies here.

Sketch:

@click.option("--list-entities", is_flag=True, help="Print class_derivation names and exit.")
def validate_spec_cmd(..., list_entities: bool = False):
    ...

def _validate_spec_merged(..., list_entities: bool = False):
    from linkml_map.utils.spec_merge import load_and_merge_specs
    merged = load_and_merge_specs(spec_files)
    if list_entities:
        cd = merged.get("class_derivations", [])
        names = sorted(
            next(iter(item)) if isinstance(item, dict) and len(item) == 1 else item.get("name", "")
            for item in (cd if isinstance(cd, list) else [])
        )
        for name in names:
            if name:
                click.echo(name)
        return  # skip schema binding
    ...

Scope

Minimal: no new public API, no changes to spec_merge.py, no schema-binding work triggered. The flag is only valid with --merge (same pattern as --entity and --emit-spec).

@dragon-ai-agent please implement the --list-entitiesflag onvalidate-spec --mergeas described in this issue. Add it tosrc/linkml_map/cli/cli.py— specifically tovalidate_spec_cmdand_validate_spec_merged. Guard it behind --mergelike the existing--entityflag. Handle both list-of-blocks and standard dict formats forclass_derivations. Add CLI integration tests following the pattern in the existing validate-spec tests.