Mercurial > repos > shellac > sam_consensus_v3
comparison env/lib/python3.9/site-packages/cwltool/schemas/v1.2.0-dev2/concepts.md @ 0:4f3585e2f14b draft default tip
"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"
author | shellac |
---|---|
date | Mon, 22 Mar 2021 18:12:50 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:4f3585e2f14b |
---|---|
1 ## References to other specifications | |
2 | |
3 **Javascript Object Notation (JSON)**: http://json.org | |
4 | |
5 **JSON Linked Data (JSON-LD)**: http://json-ld.org | |
6 | |
7 **YAML**: http://yaml.org | |
8 | |
9 **Avro**: https://avro.apache.org/docs/1.8.1/spec.html | |
10 | |
11 **Uniform Resource Identifier (URI) Generic Syntax**: https://tools.ietf.org/html/rfc3986) | |
12 | |
13 **Internationalized Resource Identifiers (IRIs)**: | |
14 https://tools.ietf.org/html/rfc3987 | |
15 | |
16 **Portable Operating System Interface (POSIX.1-2008)**: http://pubs.opengroup.org/onlinepubs/9699919799/ | |
17 | |
18 **Resource Description Framework (RDF)**: http://www.w3.org/RDF/ | |
19 | |
20 **XDG Base Directory Specification**: https://specifications.freedesktop.org/basedir-spec/basedir-spec-0.6.html | |
21 | |
22 | |
23 ## Scope | |
24 | |
25 This document describes CWL syntax, execution, and object model. It | |
26 is not intended to document a CWL specific implementation, however it may | |
27 serve as a reference for the behavior of conforming implementations. | |
28 | |
29 ## Terminology | |
30 | |
31 The terminology used to describe CWL documents is defined in the | |
32 Concepts section of the specification. The terms defined in the | |
33 following list are used in building those definitions and in describing the | |
34 actions of a CWL implementation: | |
35 | |
36 **may**: Conforming CWL documents and CWL implementations are permitted but | |
37 not required to behave as described. | |
38 | |
39 **must**: Conforming CWL documents and CWL implementations are required to behave | |
40 as described; otherwise they are in error. | |
41 | |
42 **error**: A violation of the rules of this specification; results are | |
43 undefined. Conforming implementations may detect and report an error and may | |
44 recover from it. | |
45 | |
46 **fatal error**: A violation of the rules of this specification; results are | |
47 undefined. Conforming implementations must not continue to execute the current | |
48 process and may report an error. | |
49 | |
50 **at user option**: Conforming software may or must (depending on the modal verb in | |
51 the sentence) behave as described; if it does, it must provide users a means to | |
52 enable or disable the behavior described. | |
53 | |
54 **deprecated**: Conforming software may implement a behavior for backwards | |
55 compatibility. Portable CWL documents should not rely on deprecated behavior. | |
56 Behavior marked as deprecated may be removed entirely from future revisions of | |
57 the CWL specification. | |
58 | |
59 # Data model | |
60 | |
61 ## Data concepts | |
62 | |
63 An **object** is a data structure equivalent to the "object" type in JSON, | |
64 consisting of a unordered set of name/value pairs (referred to here as | |
65 **fields**) and where the name is a string and the value is a string, number, | |
66 boolean, array, or object. | |
67 | |
68 A **document** is a file containing a serialized object, or an array of objects. | |
69 | |
70 A **process** is a basic unit of computation which accepts input data, | |
71 performs some computation, and produces output data. Examples include | |
72 CommandLineTools, Workflows, and ExpressionTools. | |
73 | |
74 An **input object** is an object describing the inputs to an invocation of | |
75 a process. | |
76 | |
77 An **output object** is an object describing the output resulting from an | |
78 invocation of a process. | |
79 | |
80 An **input schema** describes the valid format (required fields, data types) | |
81 for an input object. | |
82 | |
83 An **output schema** describes the valid format for an output object. | |
84 | |
85 **Metadata** is information about workflows, tools, or input items. | |
86 | |
87 ## Syntax | |
88 | |
89 CWL documents must consist of an object or array of objects represented using | |
90 JSON or YAML syntax. Upon loading, a CWL implementation must apply the | |
91 preprocessing steps described in the | |
92 [Semantic Annotations for Linked Avro Data (SALAD) Specification](SchemaSalad.html). | |
93 An implementation may formally validate the structure of a CWL document using | |
94 SALAD schemas located at https://github.com/common-workflow-language/cwl-v1.1/ | |
95 | |
96 ### map | |
97 | |
98 Note: This section is non-normative. | |
99 > type: array<ComplexType> | | |
100 > map<`key_field`, ComplexType> | |
101 | |
102 The above syntax in the CWL specifications means there are two or more ways to write the given value. | |
103 | |
104 Option one is a array and is the most verbose option. | |
105 | |
106 Option one generic example: | |
107 ``` | |
108 some_cwl_field: | |
109 - key_field: a_complex_type1 | |
110 field2: foo | |
111 field3: bar | |
112 - key_field: a_complex_type2 | |
113 field2: foo2 | |
114 field3: bar2 | |
115 - key_field: a_complex_type3 | |
116 ``` | |
117 | |
118 Option one specific example using [Workflow](Workflow.html#Workflow).[inputs](Workflow.html#WorkflowInputParameter): | |
119 > array<InputParameter> | | |
120 > map<`id`, `type` | InputParameter> | |
121 | |
122 | |
123 ``` | |
124 inputs: | |
125 - id: workflow_input01 | |
126 type: string | |
127 - id: workflow_input02 | |
128 type: File | |
129 format: http://edamontology.org/format_2572 | |
130 ``` | |
131 | |
132 Option two is enabled by the `map<…>` syntax. Instead of an array of entries we | |
133 use a mapping, where one field of the `ComplexType` (here named `key_field`) | |
134 becomes the key in the map, and its value is the rest of the `ComplexType` | |
135 without the key field. If all of the other fields of the `ComplexType` are | |
136 optional and unneeded, then we can indicate this with an empty mapping as the | |
137 value: `a_complex_type3: {}` | |
138 | |
139 Option two generic example: | |
140 ``` | |
141 some_cwl_field: | |
142 a_complex_type1: # this was the "key_field" from above | |
143 field2: foo | |
144 field3: bar | |
145 a_complex_type2: | |
146 field2: foo2 | |
147 field3: bar2 | |
148 a_complex_type3: {} # we accept the defualt values for "field2" and "field3" | |
149 ``` | |
150 | |
151 Option two specific example using [Workflow](Workflow.html#Workflow).[inputs](Workflow.html#WorkflowInputParameter): | |
152 > array<InputParameter> | | |
153 > map<`id`, `type` | InputParameter> | |
154 | |
155 | |
156 ``` | |
157 inputs: | |
158 workflow_input01: | |
159 type: string | |
160 workflow_input02: | |
161 type: File | |
162 format: http://edamontology.org/format_2572 | |
163 ``` | |
164 | |
165 Option two specific example using [SoftwareRequirement](#SoftwareRequirement).[packages](#SoftwarePackage): | |
166 > array<SoftwarePackage> | | |
167 > map<`package`, `specs` | SoftwarePackage> | |
168 | |
169 | |
170 ``` | |
171 hints: | |
172 SoftwareRequirement: | |
173 packages: | |
174 sourmash: | |
175 specs: [ https://doi.org/10.21105/joss.00027 ] | |
176 screed: | |
177 version: [ "1.0" ] | |
178 python: {} | |
179 ``` | |
180 ` | |
181 Sometimes we have a third and even more compact option denoted like this: | |
182 > type: array<ComplexType> | | |
183 > map<`key_field`, `field2` | ComplexType> | |
184 | |
185 For this example, if we only need the `key_field` and `field2` when specifying | |
186 our `ComplexType`s (because the other fields are optional and we are fine with | |
187 their default values) then we can abbreviate. | |
188 | |
189 Option three generic example: | |
190 ``` | |
191 some_cwl_field: | |
192 a_complex_type1: foo # we accept the default value for field3 | |
193 a_complex_type2: foo2 # we accept the default value for field3 | |
194 a_complex_type3: {} # we accept the default values for "field2" and "field3" | |
195 ``` | |
196 | |
197 Option three specific example using [Workflow](Workflow.html#Workflow).[inputs](Workflow.html#WorkflowInputParameter): | |
198 > array<InputParameter> | | |
199 > map<`id`, `type` | InputParameter> | |
200 | |
201 | |
202 ``` | |
203 inputs: | |
204 workflow_input01: string | |
205 workflow_input02: File # we accept the default of no File format | |
206 ``` | |
207 | |
208 Option three specific example using [SoftwareRequirement](#SoftwareRequirement).[packages](#SoftwarePackage): | |
209 > array<SoftwarePackage> | | |
210 > map<`package`, `specs` | SoftwarePackage> | |
211 | |
212 | |
213 ``` | |
214 hints: | |
215 SoftwareRequirement: | |
216 packages: | |
217 sourmash: [ https://doi.org/10.21105/joss.00027 ] | |
218 python: {} | |
219 ``` | |
220 | |
221 | |
222 What if some entries we want to mix the option 2 and 3? You can! | |
223 | |
224 Mixed option 2 and 3 generic example: | |
225 ``` | |
226 some_cwl_field: | |
227 my_complex_type1: foo # we accept the default value for field3 | |
228 my_complex_type2: | |
229 field2: foo2 | |
230 field3: bar2 # we did not accept the default value for field3 | |
231 # so we had to use the slightly expanded syntax | |
232 my_complex_type3: {} # as before, we accept the default values for both | |
233 # "field2" and "field3" | |
234 ``` | |
235 | |
236 Mixed option 2 and 3 specific example using [Workflow](Workflow.html#Workflow).[inputs](Workflow.html#WorkflowInputParameter): | |
237 > array<InputParameter> | | |
238 > map<`id`, `type` | InputParameter> | |
239 | |
240 | |
241 ``` | |
242 inputs: | |
243 workflow_input01: string | |
244 workflow_input02: # we use the longer way | |
245 type: File # because we want to specify the "format" too | |
246 format: http://edamontology.org/format_2572 | |
247 ``` | |
248 | |
249 Mixed option 2 and 3 specific example using [SoftwareRequirement](#SoftwareRequirement).[packages](#SoftwarePackage): | |
250 > array<SoftwarePackage> | | |
251 > map<`package`, `specs` | SoftwarePackage> | |
252 | |
253 | |
254 ``` | |
255 hints: | |
256 SoftwareRequirement: | |
257 packages: | |
258 sourmash: [ https://doi.org/10.21105/joss.00027 ] | |
259 screed: | |
260 specs: [ https://github.com/dib-lab/screed ] | |
261 version: [ "1.0" ] | |
262 python: {} | |
263 ``` | |
264 | |
265 Note: The `map<…>` (compact) versions are optional for users, the verbose option #1 is | |
266 always allowed, but for presentation reasons option 3 and 2 may be preferred | |
267 by human readers. Consumers of CWL must support all three options. | |
268 | |
269 The normative explanation for these variations, aimed at implementors, is in the | |
270 [Schema Salad specification](SchemaSalad.html#Identifier_maps). | |
271 | |
272 ## Identifiers | |
273 | |
274 If an object contains an `id` field, that is used to uniquely identify the | |
275 object in that document. The value of the `id` field must be unique over the | |
276 entire document. Identifiers may be resolved relative to either the document | |
277 base and/or other identifiers following the rules are described in the | |
278 [Schema Salad specification](SchemaSalad.html#Identifier_resolution). | |
279 | |
280 An implementation may choose to only honor references to object types for | |
281 which the `id` field is explicitly listed in this specification. | |
282 | |
283 ## Document preprocessing | |
284 | |
285 An implementation must resolve [$import](SchemaSalad.html#Import) and | |
286 [$include](SchemaSalad.html#Import) directives as described in the | |
287 [Schema Salad specification](SchemaSalad.html). | |
288 | |
289 Another transformation defined in Schema salad is simplification of data type definitions. | |
290 Type `<T>` ending with `?` should be transformed to `[<T>, "null"]`. | |
291 Type `<T>` ending with `[]` should be transformed to `{"type": "array", "items": <T>}` | |
292 | |
293 ## Extensions and metadata | |
294 | |
295 Input metadata (for example, a sample identifier) may be represented within | |
296 a tool or workflow using input parameters which are explicitly propagated to | |
297 output. Future versions of this specification may define additional facilities | |
298 for working with input/output metadata. | |
299 | |
300 Implementation extensions not required for correct execution (for example, | |
301 fields related to GUI presentation) and metadata about the tool or workflow | |
302 itself (for example, authorship for use in citations) may be provided as | |
303 additional fields on any object. Such extensions fields must use a namespace | |
304 prefix listed in the `$namespaces` section of the document as described in the | |
305 [Schema Salad specification](SchemaSalad.html#Explicit_context). | |
306 | |
307 It is recommended that concepts from schema.org are used whenever possible. | |
308 For the `$schema` field we recommend their RDF encoding: http://schema.org/version/latest/schema.rdf | |
309 | |
310 Implementation extensions which modify execution semantics must be [listed in | |
311 the `requirements` field](#Requirements_and_hints). | |
312 | |
313 # Execution model | |
314 | |
315 ## Execution concepts | |
316 | |
317 A **parameter** is a named symbolic input or output of process, with an | |
318 associated datatype or schema. During execution, values are assigned to | |
319 parameters to make the input object or output object used for concrete | |
320 process invocation. | |
321 | |
322 A **CommandLineTool** is a process characterized by the execution of a | |
323 standalone, non-interactive program which is invoked on some input, | |
324 produces output, and then terminates. | |
325 | |
326 A **workflow** is a process characterized by multiple subprocess steps, | |
327 where step outputs are connected to the inputs of downstream steps to | |
328 form a directed acylic graph, and independent steps may run concurrently. | |
329 | |
330 A **runtime environment** is the actual hardware and software environment when | |
331 executing a command line tool. It includes, but is not limited to, the | |
332 hardware architecture, hardware resources, operating system, software runtime | |
333 (if applicable, such as the specific Python interpreter or the specific Java | |
334 virtual machine), libraries, modules, packages, utilities, and data files | |
335 required to run the tool. | |
336 | |
337 A **workflow platform** is a specific hardware and software implementation | |
338 capable of interpreting CWL documents and executing the processes specified by | |
339 the document. The responsibilities of the workflow platform may include | |
340 scheduling process invocation, setting up the necessary runtime environment, | |
341 making input data available, invoking the tool process, and collecting output. | |
342 | |
343 A workflow platform may choose to only implement the Command Line Tool | |
344 Description part of the CWL specification. | |
345 | |
346 It is intended that the workflow platform has broad leeway outside of this | |
347 specification to optimize use of computing resources and enforce policies | |
348 not covered by this specification. Some areas that are currently out of | |
349 scope for CWL specification but may be handled by a specific workflow | |
350 platform include: | |
351 | |
352 * Data security and permissions | |
353 * Scheduling tool invocations on remote cluster or cloud compute nodes. | |
354 * Using virtual machines or operating system containers to manage the runtime | |
355 (except as described in [DockerRequirement](CommandLineTool.html#DockerRequirement)). | |
356 * Using remote or distributed file systems to manage input and output files. | |
357 * Transforming file paths. | |
358 * Pausing, resuming or checkpointing processes or workflows. | |
359 | |
360 Conforming CWL processes must not assume anything about the runtime | |
361 environment or workflow platform unless explicitly declared though the use | |
362 of [process requirements](#Requirements_and_hints). | |
363 | |
364 ## Generic execution process | |
365 | |
366 The generic execution sequence of a CWL process (including workflows and | |
367 command line line tools) is as follows. | |
368 | |
369 1. Load input object. | |
370 1. Load, process and validate a CWL document, yielding one or more process objects. | |
371 The [`$namespaces`](SchemaSalad.html#Explicit_context) present in the CWL document | |
372 are also used when validating and processing the input object. | |
373 1. If there are multiple process objects (due to [`$graph`](SchemaSalad.html#Document_graph)) | |
374 and which process object to start with is not specified in the input object (via | |
375 a [`cwl:tool`](#Executing_CWL_documents_as_scripts) entry) or by any other means | |
376 (like a URL fragment) then choose the process with the `id` of "#main" or "main". | |
377 1. Validate the input object against the `inputs` schema for the process. | |
378 1. Validate process requirements are met. | |
379 1. Perform any further setup required by the specific process type. | |
380 1. Execute the process. | |
381 1. Capture results of process execution into the output object. | |
382 1. Validate the output object against the `outputs` schema for the process. | |
383 1. Report the output object to the process caller. | |
384 | |
385 ## Requirements and hints | |
386 | |
387 A **process requirement** modifies the semantics or runtime | |
388 environment of a process. If an implementation cannot satisfy all | |
389 requirements, or a requirement is listed which is not recognized by the | |
390 implementation, it is a fatal error and the implementation must not attempt | |
391 to run the process, unless overridden at user option. | |
392 | |
393 A **hint** is similar to a requirement; however, it is not an error if an | |
394 implementation cannot satisfy all hints. The implementation may report a | |
395 warning if a hint cannot be satisfied. | |
396 | |
397 Optionally, implementations may allow requirements to be specified in the input | |
398 object document as an array of requirements under the field name | |
399 `cwl:requirements`. If implementations allow this, then such requirements | |
400 should be combined with any requirements present in the corresponding Process | |
401 as if they were specified there. | |
402 | |
403 Requirements specified in a parent Workflow are inherited by step processes | |
404 if they are valid for that step. If the substep is a CommandLineTool | |
405 only the `InlineJavascriptRequirement`, `SchemaDefRequirement`, `DockerRequirement`, | |
406 `SoftwareRequirement`, `InitialWorkDirRequirement`, `EnvVarRequirement`, | |
407 `ShellCommandRequirement`, `ResourceRequirement` are valid. | |
408 | |
409 *As good practice, it is best to have process requirements be self-contained, | |
410 such that each process can run successfully by itself.* | |
411 | |
412 If the same process requirement appears at different levels of the | |
413 workflow, the most specific instance of the requirement is used, that is, | |
414 an entry in `requirements` on a process implementation such as | |
415 CommandLineTool will take precedence over an entry in `requirements` | |
416 specified in a workflow step, and an entry in `requirements` on a workflow | |
417 step takes precedence over the workflow. Entries in `hints` are resolved | |
418 the same way. | |
419 | |
420 Requirements override hints. If a process implementation provides a | |
421 process requirement in `hints` which is also provided in `requirements` by | |
422 an enclosing workflow or workflow step, the enclosing `requirements` takes | |
423 precedence. | |
424 | |
425 ## Parameter references | |
426 | |
427 Parameter references are denoted by the syntax `$(...)` and may be used in any | |
428 field permitting the pseudo-type `Expression`, as specified by this document. | |
429 Conforming implementations must support parameter references. Parameter | |
430 references use the following subset of | |
431 [Javascript/ECMAScript 5.1](http://www.ecma-international.org/ecma-262/5.1/) | |
432 syntax, but they are designed to not require a Javascript engine for evaluation. | |
433 | |
434 In the following [BNF | |
435 grammar](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form), character | |
436 classes, and grammar rules are denoted in '{}', '-' denotes exclusion from a | |
437 character class, '(())' denotes grouping, '|' denotes alternates, trailing | |
438 '*' denotes zero or more repeats, '+' denote one or more repeats, '/' escapes | |
439 these special characters, and all other characters are literal values. | |
440 | |
441 <p> | |
442 <table class="table"> | |
443 <tr><td>symbol:: </td><td>{Unicode alphanumeric}+</td></tr> | |
444 <tr><td>singleq:: </td><td>[' (( {character - '} | \' ))* ']</td></tr> | |
445 <tr><td>doubleq:: </td><td>[" (( {character - "} | \" ))* "]</td></tr> | |
446 <tr><td>index:: </td><td>[ {decimal digit}+ ]</td></tr> | |
447 <tr><td>segment:: </td><td>. {symbol} | {singleq} | {doubleq} | {index}</td></tr> | |
448 <tr><td>parameter reference::</td><td>$( {symbol} {segment}*)</td></tr> | |
449 </table> | |
450 </p> | |
451 | |
452 Use the following algorithm to resolve a parameter reference: | |
453 | |
454 1. Match the leading symbol as the key | |
455 2. Look up the key in the parameter context (described below) to get the current value. | |
456 It is an error if the key is not found in the parameter context. | |
457 3. If there are no subsequent segments, terminate and return current value | |
458 4. Else, match the next segment | |
459 5. Extract the symbol, string, or index from the segment as the key | |
460 6. Look up the key in current value and assign as new current value. If | |
461 the key is a symbol or string, the current value must be an object. | |
462 If the key is an index, the current value must be an array or string. | |
463 It is an error if the key does not match the required type, or the key is not found or out | |
464 of range. | |
465 7. Repeat steps 3-6 | |
466 | |
467 The root namespace is the parameter context. The following parameters must | |
468 be provided: | |
469 | |
470 * `inputs`: The input object to the current Process. | |
471 * `self`: A context-specific value. The contextual values for 'self' are | |
472 documented for specific fields elsewhere in this specification. If | |
473 a contextual value of 'self' is not documented for a field, it | |
474 must be 'null'. | |
475 * `runtime`: An object containing configuration details. Specific to the | |
476 process type. An implementation may provide | |
477 opaque strings for any or all fields of `runtime`. These must be | |
478 filled in by the platform after processing the Tool but before actual | |
479 execution. Parameter references and expressions may only use the | |
480 literal string value of the field and must not perform computation on | |
481 the contents, except where noted otherwise. | |
482 | |
483 If the value of a field has no leading or trailing non-whitespace | |
484 characters around a parameter reference, the effective value of the field | |
485 becomes the value of the referenced parameter, preserving the return type. | |
486 | |
487 If the value of a field has non-whitespace leading or trailing characters | |
488 around a parameter reference, it is subject to string interpolation. The | |
489 effective value of the field is a string containing the leading characters, | |
490 followed by the string value of the parameter reference, followed by the | |
491 trailing characters. The string value of the parameter reference is its | |
492 textual JSON representation with the following rules: | |
493 | |
494 * Leading and trailing quotes are stripped from strings | |
495 * Objects entries are sorted by key | |
496 | |
497 Multiple parameter references may appear in a single field. This case | |
498 must be treated as a string interpolation. After interpolating the first | |
499 parameter reference, interpolation must be recursively applied to the | |
500 trailing characters to yield the final string value. | |
501 | |
502 ## Expressions (Optional) | |
503 | |
504 An expression is a fragment of [Javascript/ECMAScript | |
505 5.1](http://www.ecma-international.org/ecma-262/5.1/) code evaluated by the | |
506 workflow platform to affect the inputs, outputs, or | |
507 behavior of a process. In the generic execution sequence, expressions may | |
508 be evaluated during step 5 (process setup), step 6 (execute process), | |
509 and/or step 7 (capture output). Expressions are distinct from regular | |
510 processes in that they are intended to modify the behavior of the workflow | |
511 itself rather than perform the primary work of the workflow. | |
512 | |
513 Expressions in CWL are an optional feature and are not required to be | |
514 implemented by all consumers of CWL documents. They should be used sparingly, | |
515 when there is no other way to achieve the desired outcome. Excessive use of | |
516 expressions may be a signal that other refactoring of the tools or workflows | |
517 would benefit the author, runtime, and users of the CWL document in question. | |
518 | |
519 To declare the use of expressions, the document must include the process | |
520 requirement `InlineJavascriptRequirement`. Expressions may be used in any | |
521 field permitting the pseudo-type `Expression`, as specified by this | |
522 document. | |
523 | |
524 Expressions are denoted by the syntax `$(...)` or `${...}`. A code | |
525 fragment wrapped in the `$(...)` syntax must be evaluated as a | |
526 [ECMAScript expression](http://www.ecma-international.org/ecma-262/5.1/#sec-11). A | |
527 code fragment wrapped in the `${...}` syntax must be evaluated as a | |
528 [ECMAScript function body](http://www.ecma-international.org/ecma-262/5.1/#sec-13) | |
529 for an anonymous, zero-argument function. Expressions must return a valid JSON | |
530 data type: one of null, string, number, boolean, array, object. Other return | |
531 values must result in a `permanentFailure`. Implementations must permit any | |
532 syntactically valid Javascript and account for nesting of parenthesis or braces | |
533 and that strings that may contain parenthesis or braces when scanning for | |
534 expressions. | |
535 | |
536 The runtime must include any code defined in the ["expressionLib" field of | |
537 InlineJavascriptRequirement](#InlineJavascriptRequirement) prior to | |
538 executing the actual expression. | |
539 | |
540 Before executing the expression, the runtime must initialize as global | |
541 variables the fields of the parameter context described above. | |
542 | |
543 The effective value of the field after expression evaluation follows the | |
544 same rules as parameter references discussed above. Multiple expressions | |
545 may appear in a single field. | |
546 | |
547 Expressions must be evaluated in an isolated context (a "sandbox") which | |
548 permits no side effects to leak outside the context. Expressions also must | |
549 be evaluated in [Javascript strict mode](http://www.ecma-international.org/ecma-262/5.1/#sec-4.2.2). | |
550 | |
551 The order in which expressions are evaluated is undefined except where | |
552 otherwise noted in this document. | |
553 | |
554 An implementation may choose to implement parameter references by | |
555 evaluating as a Javascript expression. The results of evaluating | |
556 parameter references must be identical whether implemented by Javascript | |
557 evaluation or some other means. | |
558 | |
559 Implementations may apply other limits, such as process isolation, timeouts, | |
560 and operating system containers/jails to minimize the security risks associated | |
561 with running untrusted code embedded in a CWL document. | |
562 | |
563 Javascript exceptions thrown from a CWL expression must result in a | |
564 `permanentFailure` of the CWL process. | |
565 | |
566 ## Executing CWL documents as scripts | |
567 | |
568 By convention, a CWL document may begin with `#!/usr/bin/env cwl-runner` | |
569 and be marked as executable (the POSIX "+x" permission bits) to enable it | |
570 to be executed directly. A workflow platform may support this mode of | |
571 operation; if so, it must provide `cwl-runner` as an alias for the | |
572 platform's CWL implementation. | |
573 | |
574 A CWL input object document may similarly begin with `#!/usr/bin/env | |
575 cwl-runner` and be marked as executable. In this case, the input object | |
576 must include the field `cwl:tool` supplying an IRI to the default CWL | |
577 document that should be executed using the fields of the input object as | |
578 input parameters. | |
579 | |
580 The `cwl-runner` interface is required for conformance testing and is | |
581 documented in [cwl-runner.cwl](cwl-runner.cwl). | |
582 | |
583 ## Discovering CWL documents on a local filesystem | |
584 | |
585 To discover CWL documents look in the following locations: | |
586 | |
587 For each value in the `XDG_DATA_DIRS` environment variable (which is a `:` colon | |
588 separated list), check the `./commonwl` subdirectory. If `XDG_DATA_DIRS` is | |
589 unset or empty, then check using the default value for `XDG_DATA_DIRS`: | |
590 `/usr/local/share/:/usr/share/` (That is to say, check `/usr/share/commonwl/` | |
591 and `/usr/local/share/commonwl/`) | |
592 | |
593 Then check `$XDG_DATA_HOME/commonwl/`. | |
594 | |
595 If the `XDG_DATA_HOME` environment variable is unset, its default value is | |
596 `$HOME/.local/share` (That is to say, check `$HOME/.local/share/commonwl`) | |
597 | |
598 `$XDG_DATA_HOME` and `$XDG_DATA_DIRS` are from the [XDG Base Directory | |
599 Specification](http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html) |