From 0db19c2f37d3b8e117df1951774d28ac6a75d714 Mon Sep 17 00:00:00 2001 From: "Bruno P. Kinoshita" Date: Tue, 3 May 2022 21:08:27 +1200 Subject: [PATCH] Add glossary and clarification on opaque strings and identifiers --- Process.yml | 9 +++++---- concepts.md | 17 ++++++++++++----- invocation.md | 4 ++-- 3 files changed, 19 insertions(+), 11 deletions(-) diff --git a/Process.yml b/Process.yml index d7c6a933..5ec1a575 100644 --- a/Process.yml +++ b/Process.yml @@ -987,10 +987,11 @@ $graph: secondary file from that expression. To work on non-filename-preserving storage systems, portable - tool descriptions should treat `location` as an opaque - identifier and avoid constructing new values from `location`, - but should construct relative references using `basename` or - `nameroot` instead, or propagate `location` from defined inputs. + tool descriptions should treat `location` as an + [opaque identifier](#opaque-strings) and avoid constructing new + values from `location`, but should construct relative references + using `basename` or `nameroot` instead, or propagate `location` + from defined inputs. If a value in `secondaryFiles` is a string that is not an expression, it specifies that the following pattern should be applied to the path diff --git a/concepts.md b/concepts.md index 97b89448..ee57bf1d 100644 --- a/concepts.md +++ b/concepts.md @@ -56,6 +56,13 @@ compatibility. Portable CWL documents should not rely on deprecated behavior. Behavior marked as deprecated may be removed entirely from future revisions of the CWL specification. +## Glossary + +**Opaque strings**: Opaque strings +(or opaque identifiers, opaque values) are nonsensical values that are +swapped out with a real value later in the evaluation process. Workflow +and tool expressions **should not** rely on it nor try to parse it. + # Data model ## Data concepts @@ -538,11 +545,11 @@ be provided: must be 'null'. * `runtime`: An object containing configuration details. Specific to the process type. An implementation may provide - opaque strings for any or all fields of `runtime`. These must be - filled in by the platform after processing the Tool but before actual - execution. Parameter references and expressions may only use the - literal string value of the field and must not perform computation on - the contents, except where noted otherwise. + [opaque strings](#opaque-strings) for any or all fields of `runtime`. + These must be filled in by the platform after processing the Tool but + before actual execution. Parameter references and expressions may only + use the literal string value of the field and must not perform computation + on the contents, except where noted otherwise. If the value of a field has no leading or trailing non-whitespace characters around a parameter reference, the effective value of the field diff --git a/invocation.md b/invocation.md index d5302914..540ae3fb 100644 --- a/invocation.md +++ b/invocation.md @@ -104,8 +104,8 @@ the ability to accept inbound connections. The `runtime` section available in [parameter references](#Parameter_references) and [expressions](#Expressions) contains the following fields. As noted earlier, an implementation may perform deferred resolution of runtime fields by providing -opaque strings for any or all of the following fields; parameter references -and expressions may only use the literal string value of the field and must +[opaque strings](#opaque-strings) for any or all of the following fields; parameter +references and expressions may only use the literal string value of the field and must not perform computation on the contents. * `runtime.outdir`: an absolute path to the designated output directory