galaxyproject / galaxyproject/gxformat2
Hide $link shorthand behind a ConversionOptions flag
- 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
Assessment
This issue has not been assessed yet.