Convert `source_schema` and `target_schema` slot values into complex tasks

[matentzn]

I would like to propose to convert the currently simple slot source|target_schema to something more complex.

I will need a lot more stuff soon, like schema version, schema name etc;

@amc-corey-cox I would like to do this but can you tell me just how much you hat that this will break backwards compatibility? Scale from 1-1-10. I will implement this if your score is between 1-5.

[github-actions]

Summary & Context

Current state

In TransformationSpecification, both source_schema and target_schema are currently plain string fields — they hold a schema name/ID label only (transformer_model.yaml L88–91). They are not file paths, not auto-loaded, and serve purely as metadata annotations. The actual schema objects are wired in via source_schemaview / target_schemaview on the ObjectTransformer at runtime.

Motivation

The proposal is to make these fields structured objects (e.g., a SchemaReference type) carrying richer metadata:

• Schema name / title
• Schema version
• Potentially: schema URI/ID, namespace prefix, file path

This was directly motivated by issue #138 (filed 2026-03-08), where an external user (@paulmillar) discovered that these fields are opaque strings with no schema-loading behaviour. matentzn commented on #138 the same day this issue was filed, suggesting this is a planned follow-up. See also #47 (top-level slot_derivations not wired up in SchemaMapper) for a related gap in how spec metadata is used.

Backwards compatibility analysis

The break would be in YAML serialization of existing TransformationSpecification files. Any spec currently using:

source_schema: my_source
target_schema: my_target

...would need to become something like:

source_schema:
  name: my_source
  version: "1.0"
target_schema:
  name: my_target

Migration options to soften the break:

1. Union type / coercion: Accept both a plain string and a complex object (string → treated as name). This is the most backwards-compatible approach and is common in LinkML-adjacent tooling (e.g., how prefixes can be a string shorthand in some contexts).
2. Deprecation period: Keep the string form working with a deprecation warning before removing it.
3. Schema version bump: Treat this as a TransformationSpecification schema version change and add a spec_version field.

Design suggestion

A minimal SchemaReference class could look like:

SchemaReference:
  description: A reference to a LinkML schema, with optional version metadata
  attributes:
    name:
      description: The name/ID of the schema
      range: string
      required: true
    version:
      description: Version string for the schema (semver or date-based)
      range: string
    schema_uri:
      description: The URI/IRI identifier of the schema
      range: uri
    source_file:
      description: Optional file path or URL for loading the schema
      range: string

This would also give ObjectTransformer / Session a hook to auto-load the schema if source_file is set — closing the longstanding gap in #138.

Decision gate

This issue is explicitly waiting on @amc-corey-cox's backwards-compatibility pain score (1–10). If ≤5, the change proceeds. Given that source_schema/target_schema are currently metadata-only strings (largely decorative in real pipelines), the practical break may be low — existing parsers would fail on the new dict shape unless union coercion is added.

[amc-corey-cox]

@matentzn I think this is fairly low pain for me on anything I'm working one. If we go with the coercion suggested by co-pilot it feels like an easy win and I have no objections. If we don't coerce (and there might be good reason not to) this will be more likely to break some downstream but this is still a simple mechanical fix so I think it is fine to go ahead.

[amc-corey-cox]

My AI-bot told me I should say it's a 2... honestly, I suspect that is overestimating after I think about it a bit deeper. I don't think my pipeline even uses this feature currently, although it might be good to do so.

[matentzn]

Awesome, thank you @amc-corey-cox this will help me greatly. I will take it from here