Skip to content

Permalinks

Jump to bottom
Stian Soiland-Reyes edited this page Mar 26, 2018 · 20 revisions

Permalink URI scheme

The CWL permalink URI scheme is composed like this:

https://w3id.org/cwl/view/{scheme}/{commit}/{path}#{anchor}
  • https://w3id.org/cwl/view/ fixed prefix at permalink service https://w3id.org/ (/cwl is our namespace)
  • {scheme} - source code management protocol, currently only git supported:
    • {commit} - full git commit sha1 id (no branches or short commits allowed)
    • {path} - relative path to .cwl file within a checkout of that git commit
    • #{fragment} - an optional fragment, e.g. #main as-is from cwltool --print-rdf ; not passed on to server

Any git permalinks are resolved using https://view.commonwl.org/git which - if it knows about that particular git commit - will content-negotiate to provide various representations. Anyone can mint these permalinks for .cwl files for a given commit in any public or private git repository, given no uncommitted files or git submodules.

Example

Example:

..which correspond to:

Content negotiation

If git commit behind the permalink is recognized by the public CWL Viewer, then resolving it can perform content negotiation to various media types, either by using the HTTP Accept header, or by adding a ?format= parameter to the URL (e.g. to force a particular representation for browsers).

Note that some of these may perform HTTP redirects, so use curl -L or equivalent.

Accept: mediatype ?format= Description
text/html html Redirects to Browser view on workflow
application/json json (but see #166) JSON according to the CWL Viewer API
text/turtle turtle RDF Turtle format as from cwltool --print-rdf
application/ld+json jsonld RDF JSON-LD format
application/rdf+xml rdfxml RDF/XML (not recommended)
image/svg+xml svg Workflow diagram in vector-based SVG format (recommended)
image/png png Workflow diagram in bitmap PNG format
application/vnd.wf4ever.robundle+zip ro Research Object Bundle containing workflow, visualizations, manifest and annotations
application/zip zip (same as above)
text/x-yaml yaml Redirect to yaml view of the underlying CWL file
application/octet-stream raw (same as above)

For example, using curl to request RDF in Turtle format:

curl -L -H "Accept: text/turtle" https://w3id.org/cwl/view/git/933bf2a1a1cce32d88f88f136275535da9df0954/workflows/hello/hello.cwl

Or to download the image representation to the file workflow.svg:

curl -o workflow.svg -L -H "Accept: image/svg+xml" https://w3id.org/cwl/view/git/933bf2a1a1cce32d88f88f136275535da9df0954/workflows/hello/hello.cwl

Raw

If you use curl or wget without any content negotiation, the server will default to the application/octet-stream redirect to the raw YAML file in CWL format. If you are accessing the permalink with a browser it should redirect to the text/html view unless you force it with ?format=, e.g. https://w3id.org/cwl/view/git/933bf2a1a1cce32d88f88f136275535da9df0954/workflows/hello/hello.cwl?format=raw

In theory ?format=raw should work for any file in that git repository. (but see #167)

Note that the raw redirects only works for repositories hosted at https://github.com/ or https://gitlab.com/

Packed workflows

For the time being most of these representations are unfortunately not available for packed workflows containing multiple workflows in the same CWL file, as the #fragment is not submitted as part of the HTTP protocol. The permalinks (including the fragment) can still be used as global identifiers.

References

Clone this wiki locally