Cwl metadata

.cwl/cwl-metadata-checklist.md

+
+# Checklist for good CWL documents
+
+based on recommendations from:
+
+- https://www.commonwl.org/user_guide/topics/best-practices.html
+- https://www.commonwl.org/user_guide/topics/metadata-and-authorship.html 
+
+- [Design](#design)
+  - [Single-step first](#single-step-first)
+- [Dependencies](#dependencies)
+  - [Soft requirements = `hints`](#soft-requirements--hints)
+  - [Hard requirements = `requirements`](#hard-requirements--requirements)
+- [Metadata](#metadata)
+  - [Namespaces and schemas](#namespaces-and-schemas)
+
+## Design
+
+### Keep it Simple: Single-step
+
+- follow the [KISS principle](https://en.wikipedia.org/wiki/KISS_principle)
+- a `CommandLineTool` document should only execute one process
+- use `Workflow` documents to design more complex, multi-step pipelines
+- use `scatter` to execute the process on multiple inputs
+- do not hard code input, output paths
+
+## Dependencies
+
+### Soft requirements = `hints`
+
+Specify software and resource requirements under `hints`
+
+- add `SoftwareRequirement` to specify software version and reference
+  - `package: ` name of the software or package
+  - `specs: ` reference url from https://identifiers.org/biotools/ or SciCrunch https://identifiers.org/rrid/
+  - `version: [ "0.11.9" ]`
+- add `DockerRequirement`
+  - reference a local `Dockerfile` or a published Docker image
+- add `ResourceRequirement` to specify the required compute resources
+
+### Hard requirements = `requirements`
+
+Use the `requirements` primarily to specify hard requirements needed to run the current `CommandLineTool` or `Workflow` document
+
+## Metadata
+
+### Namespaces and schemas
+
+Adding namespaces and schemas allows to reuse them elsewhere in a CWL document
+
+```yaml
+$namespaces:
+  s: https://schema.org/
+  edam: http://edamontology.org/
+
+$schemas:
+  - https://schema.org/version/latest/schemaorg-current-https.rdf
+  - http://edamontology.org/EDAM_1.18.owl
+```
+
+### Attribute authors and contributors
+
+```yaml
+s:author:
+  - class: s:Person
+    s:identifier: <author ORCID>
+    s:email: mailto:<author email>
+    s:name: <author name>
+
+s:contributor:
+  - class: s:Person
+    s:identifier: <contributor ORCID>
+    s:email: mailto:<contributor email>
+    s:name: <contributor name>
+
+s:citation: <DOI to software paper>
+s:codeRepository: <URL to software repo (e.g. github)>
+s:dateCreated: "2016-12-13"
+s:license: <URL to license, e.g. from https://spdx.org/licenses/> 
+```