Merge remote-tracking branch 'origin/clarify-package' into v1.0-errata

Author: Peter Amstutz

site/cwlsite.cwl

@@ -26,7 +26,7 @@ inputs:
           rdfs_target: string
   brandimg: File
   empty:
-    type: string
+    type: string?
     default: ""
 
 outputs:

v1.0/CommandLineTool.yml

@@ -46,6 +46,8 @@ $graph:
       slightly different behavior in v1.0.1.
 
         * 13 July 2016: Mark `baseCommand` as optional and update descriptive text.
+        * 14 November 2016: Clarify [SoftwareRequirement](#SoftwareRequirement)
+          `spec` fields.
         * 12 March 2017:
           * Mark `default` as not required for link checking.
           * Add note that files in InitialWorkDir must have path in output directory.
@@ -716,26 +718,59 @@ $graph:
   fields:
     - name: package
       type: string
-      doc: "The common name of the software to be configured."
+      doc: |
+        The name of the software to be made available. If the name is
+        common, inconsistent, or otherwise ambiguous it should be combined with
+        one or more identifiers in the `specs` field.
     - name: version
       type: string[]?
-      doc: "The (optional) version of the software to configured."
+      doc: |
+        The (optional) versions of the software that are known to be
+        compatible.
     - name: specs
       type: string[]?
       doc: |
-        Must be one or more IRIs identifying resources for installing or
-        enabling the software.  Implementations may provide resolvers which map
-        well-known software spec IRIs to some configuration action.
-
-        For example, an IRI `https://packages.debian.org/jessie/bowtie` could
-        be resolved with `apt-get install bowtie`.  An IRI
-        `https://anaconda.org/bioconda/bowtie` could be resolved with `conda
+        One or more [IRI](https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier)s
+        identifying resources for installing or enabling the software named in
+        the `package` field. Implementations may provide resolvers which map
+        these software identifer IRIs to some configuration action; or they can
+        use only the name from the `package` field on a best effort basis.
+
+        For example, the IRI https://packages.debian.org/bowtie could
+        be resolved with `apt-get install bowtie`. The IRI
+        https://anaconda.org/bioconda/bowtie could be resolved with `conda
         install -c bioconda bowtie`.
 
-        Tools may also provide IRIs to index entries such as
-        [RRID](http://www.identifiers.org/rrid/), such as
-        `http://identifiers.org/rrid/RRID:SCR_005476`
-
+        IRIs can also be system independent and used to map to a specific
+        software installation or selection mechanism.
+        Using [RRID](https://www.identifiers.org/rrid/) as an example:
+        https://identifiers.org/rrid/RRID:SCR_005476
+        could be fulfilled using the above mentioned Debian or bioconda
+        package, a local installation managed by [Environement Modules](http://modules.sourceforge.net/),
+        or any other mechanism the platform chooses. IRIs can also be from
+        identifer sources that are discipline specific yet still system
+        independent. As an example, the equivalent [ELIXIR Tools and Data
+        Service Registry](https://bio.tools) IRI to the previous RRID example is
+        https://bio.tools/tool/bowtie2/version/2.2.8.
+        If supported by a given registry, implementations are encouraged to
+        query these system independent sofware identifier IRIs directly for
+        links to packaging systems.
+
+        A site specific IRI can be listed as well. For example, an academic
+        computing cluster using Environement Modules could list the IRI
+        `https://hpc.example.edu/modules/bowtie-tbb/1.22` to indicate that
+        `module load bowtie-tbb/1.1.2` should be executed to make available
+        `bowtie` version 1.1.2 compiled with the TBB library prior to running
+        the accompanying Workflow or CommandLineTool. Note that the example IRI
+        is specific to a particular institution and computing environment as
+        the Environment Modules system does not have a common namespace or
+        standardized naming convention.
+
+        This last example is the least portable and should only be used if
+        mechanisms based off of the `package` field or more generic IRIs are
+        unavailable or unsuitable. While harmless to other sites, site specific
+        software IRIs should be left out of shared CWL descriptions to avoid
+        clutter.
 
 - name: Dirent
   type: record

v1.1.0-dev1/CommandLineTool.yml

@@ -86,7 +86,10 @@ $graph:
 
       Post v1.0 release changes to the spec.
 
-        * 13 July 2016: Mark `baseCommand` as optional and update descriptive text.
+        * 13 July 2016: Mark `baseCommand` as optional and update descriptive
+          text.
+        * 14 November 2016: Clarify [SoftwareRequirement](#SoftwareRequirement)
+          `spec` fields.
 
       ## Purpose
 
@@ -746,26 +749,60 @@ $graph:
   fields:
     - name: package
       type: string
-      doc: "The common name of the software to be configured."
+      doc: |
+        The name of the software to be made available. If the name is
+        common, inconsistent, or otherwise ambiguous it should be combined with
+        one or more identifiers in the `specs` field.
     - name: version
       type: string[]?
-      doc: "The (optional) version of the software to configured."
+      doc: |
+        The (optional) versions of the software that are known to be
+        compatible.
     - name: specs
       type: string[]?
+      jsonldPredicate: {_type: "@id", noLinkCheck: true}
       doc: |
-        Must be one or more IRIs identifying resources for installing or
-        enabling the software.  Implementations may provide resolvers which map
-        well-known software spec IRIs to some configuration action.
-
-        For example, an IRI `https://packages.debian.org/jessie/bowtie` could
-        be resolved with `apt-get install bowtie`.  An IRI
-        `https://anaconda.org/bioconda/bowtie` could be resolved with `conda
+        One or more [IRI](https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier)s
+        identifying resources for installing or enabling the software named in
+        the `package` field. Implementations may provide resolvers which map
+        these software identifer IRIs to some configuration action; or they can
+        use only the name from the `package` field on a best effort basis.
+
+        For example, the IRI https://packages.debian.org/bowtie could
+        be resolved with `apt-get install bowtie`. The IRI
+        https://anaconda.org/bioconda/bowtie could be resolved with `conda
         install -c bioconda bowtie`.
 
-        Tools may also provide IRIs to index entries such as
-        [RRID](http://www.identifiers.org/rrid/), such as
-        `http://identifiers.org/rrid/RRID:SCR_005476`
-
+        IRIs can also be system independent and used to map to a specific
+        software installation or selection mechanism.
+        Using [RRID](https://www.identifiers.org/rrid/) as an example:
+        https://identifiers.org/rrid/RRID:SCR_005476
+        could be fulfilled using the above mentioned Debian or bioconda
+        package, a local installation managed by [Environement Modules](http://modules.sourceforge.net/),
+        or any other mechanism the platform chooses. IRIs can also be from
+        identifer sources that are discipline specific yet still system
+        independent. As an example, the equivalent [ELIXIR Tools and Data
+        Service Registry](https://bio.tools) IRI to the previous RRID example is
+        https://bio.tools/tool/bowtie2/version/2.2.8.
+        If supported by a given registry, implementations are encouraged to
+        query these system independent sofware identifier IRIs directly for
+        links to packaging systems.
+
+        A site specific IRI can be listed as well. For example, an academic
+        computing cluster using Environement Modules could list the IRI
+        `https://hpc.example.edu/modules/bowtie-tbb/1.22` to indicate that
+        `module load bowtie-tbb/1.1.2` should be executed to make available
+        `bowtie` version 1.1.2 compiled with the TBB library prior to running
+        the accompanying Workflow or CommandLineTool. Note that the example IRI
+        is specific to a particular institution and computing environment as
+        the Environment Modules system does not have a common namespace or
+        standardized naming convention.
+
+        This last example is the least portable and should only be used if
+        mechanisms based off of the `package` field or more generic IRIs are
+        unavailable or unsuitable. While harmless to other sites, site specific
+        software IRIs should be left out of shared CWL descriptions to avoid
+        clutter.
 
 - name: Dirent
   type: record