Skip to content Skip to footer

Workflow RO-Crate (DRAFT)

Workflow RO-Crate (DRAFT)

Workflow RO-Crate

Please note this is a draft spec and subject to change. Please leave any suggestions and comments here: https://github.com/seek4science/seek/issues/183

Workflow RO-Crates are a specialization of RO-Crate for packaging an executable workflow with all necessary documentation. It is aligned with, and intends to strictly extend, the more general Bioschemas ComputatioonalWorkflow profile.

WorkflowHub uses Workflow RO-Crates as an exchange format for users to upload a packaged workflow.

Concepts

This section uses terminology from the RO-Crate 1.1 specification.

Main Workflow

The Crate MUST contain a data entity of type ["File", "SoftwareSourceCode", "ComputationalWorkflow"] as the Main Workflow.

The Crate MUST refer to the Main Workflow via mainEntity.

The Main Workflow MUST refer to its type via programmingLanguage.

Main Workflow CWL Description

The Crate COULD contain a data entity of type ["File", "SoftwareSourceCode", "HowTo"] as the Main Workflow CWL Description.

If present the Main Workflow MUST refer to the Main Workflow CWL Description via subjectOf.

Main Workflow Diagram

The Crate COULD contain a Main Workflow Diagram, indicated as a data entity of type ["File", "ImageObject"].

If Main Workflow Diagram is present, the Main Workflow MUST refer to it via image.

Crate

The Crate MUST specify a license.

The Crate SHOULD contain README.md at the root level.

The Crate COULD contain a Dataset (directory) data entity of type ["Dataset"] named “test” to hold tests.

The Crate COULD contain a Dataset (directory) data entity of type ["Dataset"] named “examples” to hold examples.

WorkflowHub-specific Features/Requirements

File Format

The Workflow RO-Crate must be zipped, and have the file extension .crate.zip to be recognized by WorkflowHub.

Extracted Metadata

WorkflowHub will extract and expose the following properties from the Crate entity (./) in ro-crate-metadata.jsonld:

  • name - This will be shown as the title of the workflow.
  • description - This will be shown as the description of the workflow. If it is not present, but a README.md file is available in the root of the crate, that will be rendered instead.
  • author - These will be shown as “creators” of the workflow.
  • license - See below.
  • keywords - These will be shown as “tags”, and can be filtered over.

If the Main Workflow CWL Description is present it will be parsed and the inputs, outputs and steps will be listed on the workflow’s page in the Hub.

If the Main Workflow Diagram is present, it will also be rendered on the page.

Supported Workflow Types

WorkflowHub currently supports CWL, Galaxy, KNIME and Nextflow workflow types.

To ensure compatibility, please include one of the following in the RO-Crate metadata, and refer to it from the Main Workflow’s programmingLanguage.

CWL

{
  "@id": "#cwl",
  "@type": "ComputerLanguage",
  "name": "Common Workflow Language",
  "alternateName": "CWL",
  "identifier": {
    "@id": "https://w3id.org/cwl/v1.0/"
  },
  "url": {
    "@id": "https://www.commonwl.org/"
  }
}

Galaxy

{
  "@id": "#galaxy",
  "@type": "ComputerLanguage",
  "name": "Galaxy",
  "identifier": {
    "@id": "https://galaxyproject.org/"
  },
  "url": {
    "@id": "https://galaxyproject.org/"
  }
}

KNIME

{
  "@id": "#knime",
  "@type": "ComputerLanguage",
  "name": "KNIME",
  "identifier": {
    "@id": "https://www.knime.com/"
  },
  "url": {
    "@id": "https://www.knime.com/"
  }
}

Nextflow

{
  "@id": "#nextflow",
  "@type": "ComputerLanguage",
  "name": "Nextflow",
  "identifier": {
    "@id": "https://www.nextflow.io/"
  },
  "url": {
    "@id": "https://www.nextflow.io/"
  }
}

Snakemake

{
  "@id": "#snakemake",
  "@type": "ComputerLanguage",
  "name": "Snakemake",
  "identifier": {
    "@id": "https://doi.org/10.1093/bioinformatics/bts480"
  },
  "url": {
    "@id": "https://snakemake.readthedocs.io"
  }
}

Supported Licenses

Although the Crate’s license field should be a URL, WorkflowHub currently accepts a string of one of the following values (on the left):

ro-crate-metadata.jsonld Example

A minimal example of Workflow RO-Crate metadata, containing a CWL workflow, an SVG diagram of that workflow and a README file.

{
  "@context": "https://w3id.org/ro/crate/1.1/context",
  "@graph": [
    {
      "@id": "ro-crate-metadata.jsonld",
      "@type": "CreativeWork",
      "about": {
        "@id": "./"
      },
      "conformsTo": {
        "@id": "https://w3id.org/ro/crate/1.1"
      }
    },
    {
      "@id": "ro-crate-preview.html",
      "@type": "CreativeWork",
      "about": {
        "@id": "./"
      }
    },
    {
      "@id": "./",
      "@type": "Dataset",
      "name": "Example Workflow",
      "description": "An example workflow RO-Crate",
      "license": "Apache-2.0",
      "mainEntity": {
        "@id": "example_workflow.cwl"
      },
      "hasPart": [
        {
          "@id": "example_workflow.cwl"
        },
        {
          "@id": "diagram.svg"
        },
        {
          "@id": "README.md"
        }
      ]
    },
    {
      "@id": "example_workflow.cwl",
      "@type": [
        "File",
        "SoftwareSourceCode",
        "HowTo"
      ],
      "programmingLanguage": {
        "@id": "#cwl"
      },
      "name": "Example Workflow",
      "image": {
        "@id": "diagram.svg"
      }
    },
    {
      "@id": "diagram.svg",
      "name": "Example Workflow Diagram",
      "@type": [
        "File",
        "ImageObject"
      ]
    },
    {
      "@id": "README.md",
      "@type": "File"
    },
    {
      "@id": "#cwl",
      "@type": "ComputerLanguage",
      "name": "Common Workflow Language",
      "alternateName": "CWL",
      "identifier": {
        "@id": "https://w3id.org/cwl/v1.0/"
      },
      "url": {
        "@id": "https://www.commonwl.org/"
      }
    }
  ]
}