Merge pull request #252 from common-workflow-language/description2doc

Description2doc

Author: mr-c

draft-3/Workflow.yml

@@ -378,8 +378,8 @@ $graph:
   extends: "#Process"
   documentRoot: true
   specialize:
-    specializeFrom: "#OutputParameter"
-    specializeTo: "#WorkflowOutputParameter"
+    - specializeFrom: "#OutputParameter"
+      specializeTo: "#WorkflowOutputParameter"
   doc: |
     A workflow describes a set of **steps** and the **dependencies** between
     those processes.  When a process produces output that will be consumed by a

draft-3/salad/schema_salad/metaschema/metaschema.yml

@@ -302,8 +302,8 @@ $graph:
   extends: ["#NamedType", "#RecordSchema", "#SchemaDefinedType"]
   documentRoot: true
   specialize:
-    specializeFrom: "#RecordField"
-    specializeTo: "#SaladRecordField"
+    - specializeFrom: "#RecordField"
+      specializeTo: "#SaladRecordField"
   fields:
     - name: abstract
       type: ["null", boolean]

v1.0/Process.yml

@@ -99,7 +99,7 @@ $graph:
         As a special case, if the `path` field is provided but the `location`
         field is not, an implementation may assign the value of the `path`
         field to `location`, and remove the `path` field.
-        
+
         If the `path` contains [POSIX shell metacharacters](http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02)
         (`|`,`&`, `;`, `<`, `>`, `(`,`)`, `$`,`` ` ``, `\`, `"`, `'`,
         `<space>`, `<tab>`, and `<newline>`) or characters
@@ -260,7 +260,7 @@ $graph:
         must not be used in any other context.  The command line tool being
         executed must be able to to access the directory at `path` using the POSIX
         `opendir(2)` syscall.
-        
+
         If the `path` contains [POSIX shell metacharacters](http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02)
         (`|`,`&`, `;`, `<`, `>`, `(`,`)`, `$`,`` ` ``, `\`, `"`, `'`,
         `<space>`, `<tab>`, and `<newline>`) or characters
@@ -305,6 +305,13 @@ $graph:
 - name: SchemaBase
   type: record
   abstract: true
+  fields:
+    - name: label
+      type:
+        - "null"
+        - string
+      jsonldPredicate: "rdfs:label"
+      doc: "A short, human-readable label of this object."
 
 
 - name: Parameter
@@ -315,19 +322,6 @@ $graph:
     Define an input or output parameter to a process.
 
   fields:
-    - name: label
-      type:
-        - "null"
-        - string
-      jsonldPredicate: "rdfs:label"
-      doc: "A short, human-readable label of this parameter object."
-
-    - name: description
-      type:
-        - "null"
-        - string
-      jsonldPredicate: "rdfs:comment"
-      doc: "A long, human-readable description of this parameter object."
     - name: secondaryFiles
       type:
         - "null"
@@ -385,6 +379,13 @@ $graph:
         indicate whether it is valid to stream file contents using a named
         pipe.  Default: `false`.
 
+    - name: doc
+      type:
+        - string?
+        - string[]?
+      doc: "A documentation string for this type, or an array of strings which should be concatenated."
+      jsonldPredicate: "rdfs:comment"
+
 
 - type: enum
   name: Expression
@@ -446,6 +447,10 @@ $graph:
     - name: inputBinding
       type: [ "null", "#InputBinding" ]
       jsonldPredicate: "cwl:inputBinding"
+    - name: label
+      type: string?
+      jsonldPredicate: "rdfs:label"
+      doc: "A short, human-readable label of this process object."
 
 
 - name: InputRecordSchema
@@ -685,7 +690,7 @@ $graph:
         - string
       jsonldPredicate: "rdfs:label"
       doc: "A short, human-readable label of this process object."
-    - name: description
+    - name: doc
       type:
         - "null"
         - string

v1.0/Workflow.yml

@@ -399,7 +399,7 @@ $graph:
       type: string?
       jsonldPredicate: "rdfs:label"
       doc: "A short, human-readable label of this process object."
-    - name: description
+    - name: doc
       type: string?
       jsonldPredicate: "rdfs:comment"
       doc: "A long, human-readable description of this process object."
@@ -433,8 +433,8 @@ $graph:
   extends: "#Process"
   documentRoot: true
   specialize:
-    specializeFrom: "#OutputParameter"
-    specializeTo: "#WorkflowOutputParameter"
+    - specializeFrom: "#OutputParameter"
+      specializeTo: "#WorkflowOutputParameter"
   doc: |
     A workflow describes a set of **steps** and the **dependencies** between
     those steps.  When a step produces output that will be consumed by a

v1.0/salad/schema_salad/makedoc.py

@@ -213,17 +213,27 @@ def __init__(self, toc, j, renderlist, redirects):
                  ("docAfter" not in f))):
                 self.render_type(f, 1)
 
-    def typefmt(self, tp, redirects, nbsp=False):
-        # type: (Any, Dict[str, str], bool) -> Union[str, unicode]
+    def typefmt(self, tp, redirects, nbsp=False, jsonldPredicate=None):
+        # type: (Any, Dict[str, str], bool, Dict[str, str]) -> Union[str, unicode]
         global primitiveType
         if isinstance(tp, list):
             if nbsp and len(tp) <= 3:
-                return "&nbsp;|&nbsp;".join([self.typefmt(n, redirects) for n in tp])
+                return "&nbsp;|&nbsp;".join([self.typefmt(n, redirects, jsonldPredicate=jsonldPredicate) for n in tp])
             else:
                 return " | ".join([self.typefmt(n, redirects) for n in tp])
         if isinstance(tp, dict):
             if tp["type"] == "https://w3id.org/cwl/salad#array":
-                return "array&lt;%s&gt;" % (self.typefmt(tp["items"], redirects, nbsp=True))
+                ar = "array&lt;%s&gt;" % (self.typefmt(tp["items"], redirects, nbsp=True))
+                if jsonldPredicate and "mapSubject" in jsonldPredicate:
+                    if "mapPredicate" in jsonldPredicate:
+                        ar += " | map&lt;%s.%s,&nbsp;%s.%s&gt" % (self.typefmt(tp["items"], redirects),
+                                                           jsonldPredicate["mapSubject"],
+                                                           self.typefmt(tp["items"], redirects),
+                                                           jsonldPredicate["mapPredicate"])
+                    ar += " | map&lt;%s.%s,&nbsp;%s&gt" % (self.typefmt(tp["items"], redirects),
+                                                          jsonldPredicate["mapSubject"],
+                                                          self.typefmt(tp["items"], redirects))
+                return ar
             if tp["type"] in ("https://w3id.org/cwl/salad#record", "https://w3id.org/cwl/salad#enum"):
                 frg = schema.avro_name(tp["name"])
                 if tp["name"] in redirects:
@@ -345,7 +355,9 @@ def extendsfrom(item, ex):
                 rfrg = schema.avro_name(i["name"])
                 tr = "<td><code>%s</code></td><td>%s</td><td>%s</td>"\
                     "<td>%s</td>" % (
-                        rfrg, self.typefmt(tp, self.redirects), opt,
+                        rfrg, self.typefmt(tp, self.redirects,
+                                           jsonldPredicate=i.get("jsonldPredicate")),
+                        "Optional" if opt else "Required",
                         mistune.markdown(desc))
                 if opt:
                     required.append(tr)

v1.0/salad/schema_salad/metaschema/import_include.md

@@ -110,3 +110,67 @@ This becomes:
   }
 }
 ```
+
+
+## Mixin
+
+During preprocessing traversal, an implementation must resolve `$mixin`
+directives.  An `$mixin` directive is an object consisting of the field
+`$mixin` specifying resource by URI string.  If there are additional fields in
+the `$mixin` object, these fields override fields in the object which is loaded
+from the `$mixin` URI.
+
+The URI string must be resolved to an absolute URI using the link resolution
+rules described previously.  Implementations must support loading from `file`,
+`http` and `https` resources.  The URI referenced by `$mixin` must be loaded
+and recursively preprocessed as a Salad document.  The external imported
+document must inherit the context of the importing document, however the file
+URI for processing the imported document must be the URI used to retrieve the
+imported document.  The `$mixin` URI must not include a document fragment.
+
+Once loaded and processed, the `$mixin` node is replaced in the document
+structure by the object or array yielded from the import operation.
+
+URIs may reference document fragments which refer to specific an object in
+the target document.  This indicates that the `$mixin` node must be
+replaced by only the object with the appropriate fragment identifier.
+
+It is a fatal error if an import directive refers to an external resource
+or resource fragment which does not exist or is not accessible.
+
+### Mixin example
+
+mixin.yml:
+```
+{
+  "hello": "world",
+  "carrot": "orange"
+}
+
+```
+
+parent.yml:
+```
+{
+  "form": {
+    "bar": {
+      "$mixin": "mixin.yml"
+      "carrot": "cake"
+      }
+  }
+}
+
+```
+
+This becomes:
+
+```
+{
+  "form": {
+    "bar": {
+      "hello": "world",
+      "carrot": "cake"
+    }
+  }
+}
+```

v1.0/salad/schema_salad/metaschema/metaschema.yml

@@ -140,13 +140,15 @@ $graph:
       jsonldPredicate:
         _id: "sld:specializeFrom"
         _type: "@id"
+        refScope: 1
 
     - name: specializeTo
       type: string
       doc: "The new data type to replace with"
       jsonldPredicate:
         _id: "sld:specializeTo"
         _type: "@id"
+        refScope: 1
 
 
 - name: NamedType
@@ -168,7 +170,7 @@ $graph:
         - string?
         - string[]?
       doc: "A documentation string for this type, or an array of strings which should be concatenated."
-      jsonldPredicate: "sld:doc"
+      jsonldPredicate: "rdfs:comment"
 
     - name: docParent
       type: string?
@@ -242,8 +244,7 @@ $graph:
   extends: [NamedType, RecordSchema, SchemaDefinedType]
   documentRoot: true
   specialize:
-    specializeFrom: "#RecordField"
-    specializeTo: "#SaladRecordField"
+    RecordField: SaladRecordField
   fields:
     - name: abstract
       type: boolean?
@@ -271,7 +272,10 @@ $graph:
         base record as a template.  For each field inherited from the base
         record, replace any instance of the type `specializeFrom` with
         `specializeTo`.
-
+      jsonldPredicate:
+        _id: "sld:specialize"
+        mapSubject: specializeFrom
+        mapPredicate: specializeTo
 
 - name: SaladEnumSchema
   type: record

v1.0/salad/schema_salad/metaschema/metaschema_base.yml

@@ -53,7 +53,7 @@ $graph:
       type: string?
       doc: |
         A documentation string for this field
-      jsonldPredicate: "sld:doc"
+      jsonldPredicate: "rdfs:comment"
 
     type:
       type: