Semantic validation collision: is_a in ClassDerivation rejects target schema class names

[amc-corey-cox]

Summary

ClassDerivation.is_a is defined in transformer_model.yaml with range: ElementDerivation (i.e., it points to another derivation in the spec), but example specs and likely user expectations use it to mean "the derived target class `is_a` a class in the target schema."

Discovery

Surfaced while testing linkml-map against linkml 1.11.0rc3. The personinfo-to-agent.transform.yaml example failed semantic validation:

```
$.class_derivations[2].is_a: 'Entity' is not valid under any of the given schemas
```

The example:

```yaml
class_derivations:
Agent:
is_a: Entity # 'Entity' is a class in the target schema
populated_from: Person
```

The model (`src/linkml_map/datamodel/transformer_model.yaml:189-191`):

```yaml
is_a:
range: ElementDerivation
slot_uri: linkml:is_a
```

linkml 1.10 was lenient enough to accept the example; 1.11rc3's tighter any_of resolution rejects it. The semantic validation feature added in #207 is what now enforces this contract — the example presumably loaded fine before #207 landed.

The semantic question

is_a here has two plausible meanings:

1. Spec-internal inheritance — "this ClassDerivation derives from another ClassDerivation in this spec" (matches the model)
2. Target-schema inheritance — "the synthesized target class `is_a` `Entity` in the target schema" (matches the example, and arguably matches LinkML convention, since is_a in plain LinkML schemas references target classes)

Options

• A. Widen the model: allow target schema class names in is_a. Either change `range:` to a union of `ElementDerivation` and string, or relax the validator to accept either.
• B. Narrow to the model: keep `range: ElementDerivation`, fix the example, document is_a as spec-internal-only.
• C. Dual-meaning: validator resolves as derivation first, falls back to target schema class lookup. Most permissive but requires the validator to know the target schema.

This is a design call, not a quick fix.

Related

• Add semantic validation to validate-spec #207 — semantic validation that newly enforces this
• This blocks running the existing personinfo-to-agent example against the 1.11+ validator stack

Needed for

v0.5.3 release. The existing example must validate cleanly before we ship 0.5.3 against the linkml GA.

[github-actions]

Analysis & Summary

Root cause: is_a already has dual semantics in the codebase

Code inspection reveals the current code already treats is_a with both meanings simultaneously, which is what the example relies on:

• transformer/transformer.py:375 — uses cd.is_a to look up a parent ClassDerivation by name in the spec (spec-internal inheritance). This enables one derivation to inherit slots from another.
• inference/schema_mapper.py:224 — directly copies class_derivation.is_a to target_class.is_a (target-schema inheritance). The string value lands verbatim as the target class's is_a.

In the example, Entity is actually defined as an empty ClassDerivation (line 28, Entity: with no body), so is_a: Entity simultaneously:

1. Makes Agent ClassDerivation inherit spec-level settings from Entity ClassDerivation
2. Sets Agent.is_a = Entity in the generated target schema

The dual use is baked into the engine. This isn't a design choice that was missed — it's load-bearing behavior.

Why it broke now

The failure is a JSON schema validation regression from LinkML 1.11rc3's stricter any_of resolution for abstract range types. When range: ElementDerivation (abstract), LinkML 1.10 accepted a plain string reference; 1.11rc3 generates a tighter JSON schema that validates the string against each concrete subtype's schema and rejects it.

The #207 semantic validator is an independent (secondary) concern — the error shown ('Entity' is not valid under any of the given schemas) is from the linkml core JSON schema validator, not from the new semantic checks.

Recommended fix: Option A, but targeted

The cleanest fix is narrowing the range on is_a specifically for ClassDerivation. Since ClassDerivation.is_a can reference either a spec-internal derivation name or a target schema class name, both reducible to a string key, the range should reflect that:

# In ElementDerivation (or overridden on ClassDerivation):
is_a:
  range: ClassReference   # existing string typedef, already used for target class names
  slot_uri: linkml:is_a

This aligns the declared model with what the engine actually uses (_find_class_derivation_by_name looks up by string name; schema_mapper assigns the string to target_class.is_a), and will pass LinkML 1.11's stricter validator without changing any runtime behavior.

Alternatively, add an any_of constraint:

is_a:
  any_of:
    - range: ElementDerivation
    - range: ClassReference
  slot_uri: linkml:is_a

Impact

• Blocks: v0.5.3 release (existing example must validate against linkml GA)
• Scope: Model change only; zero runtime behavior change (engine already treats is_a as a string in both usages)
• Test: After the fix, just test + validating personinfo-to-agent.transform.yaml against the target schema should pass cleanly