galaxyproject / galaxyproject/gxformat2

Hide $link shorthand behind a ConversionOptions flag

Open
#209 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
14
Forks
7
Avg merge
2h 49m
Merged PRs (30d)
8

Description

## Summary

The `$link` shorthand in Format2 step `state:` blocks is a gxformat2-specific shorthand handled purely by `_resolve_links` / `_pre_clean_steps` in `gxformat2/normalized/_format2.py` — it has no representation in the schema or in any pydantic model. PR #208 fixed one type-permissiveness bug in this path (int/float `$link` value coerced to str). The broader question is whether the entire `$link` mechanism should sit behind a flag similar to `ConversionOptions.legacy_compat`, so:

1. Consumers that don't want the shorthand can opt out and get strict-schema-only behavior.
2. A future major release can flip the default off and document `$link` as a deprecated input form.
3. The mechanism's surface area becomes auditable in one place rather than implicit-everywhere.

## Why this is worth doing

- `$link` is invisible to anyone reading `schema/v19_09/workflow.yml` or the pydantic models. It's a hidden second language.
- Equivalent expressivity is available via the explicit `in:` + `state` connection forms already in the schema.
- The shorthand interacts subtly with state-path encoding (pipe-separated keys, list-element handling) that is not documented anywhere except the `_resolve_links` implementation.
- Type permissiveness bugs in this path (e.g. the int-coerce fix in PR #208) suggest the path is under-tested vs. its expressive surface.

## Proposed approach

Either a separate `link_shorthand: bool = True` option on `ConversionOptions`, or fold under a generic `format2_shorthand: bool = True` umbrella that could later cover other shorthand desugarings (the `mapPredicate: source` list form, dict-form `in:` value-as-source, etc).

When off:
- `$link` in `state:` is left as-is (or rejected with a clear error message).
- Strict-schema validation can run without the implicit pre-pass.

When on (default): current behavior.

## Tests

- Round-trip a fixture using `$link` with the option off; expect either passthrough or a clear error.
- Audit `_resolve_links` for other type permissiveness questions (list of `$link` entries, nested `$link` inside arrays, `$link` with non-scalar values).

Follow-up to PR #208 (issue #205).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.