Skip to content Skip to footer

Workflow RO-Crate profile 1.0

Workflow RO-Crate

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 extends the more general Bioschemas ComputationalWorkflow profile.

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

Extension profiles

Several extensions of Workflow RO-Crate exists:

Concepts

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

Context

The Crate JSON-LD MUST be valid according to RO-Crate 1.1 and SHOULD use the RO-Crate 1.1 @context https://w3id.org/ro/crate/1.1/context

Metadata File Descriptor

The Metadata File Descriptor conformsTo SHOULD be an array that contains at least https://w3id.org/ro/crate/1.1 and https://w3id.org/workflowhub/workflow-ro-crate/1.0

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.

Tip: See RO-Crate specification on Workflows and Scripts for details.

Main Workflow CWL Description

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

A Main Workflow CWL Description SHOULD have https://w3id.org/workflowhub/workflow-ro-crate#cwl as its programmingLanguage with a corresponding contextual entity.

If Main Workflow CWL Description is present, the Main Workflow MUST refer to it the 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 license is assumed to apply to any content of the crate, unless overriden by license on individual File entities.

The Crate SHOULD contain a File README.md at the root level. If present, it SHOULD be about the Crate ./ and SHOULD have text/markdown as its encodingFormat.

The Crate COULD contain a Dataset (directory) data entity of type ["Dataset"] with identifier test/ to hold tests.

The Crate COULD contain a Dataset (directory) data entity of type ["Dataset"] with identifier examples/ to hold examples.

Bioschemas Computational Workflow profile

The ComputationalWorkflow description of the Main Workflow SHOULD comply with Bioschemas ComputationalWorkflow profile version 1.0 or later.

Conformance with the Bioschemas profile SHOULD be indicated with a conformsTo on the Main Workflow entity.

Tip: See RO-Crate 1.1: Complying with Bioschemas Computational Workflow profile

WorkflowHub-specific Features/Requirements

File Format

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

The ro-crate-metadata.json file SHOULD be directly in the root of the zip archive, so that the whole Zip becomes the RO-Crate Root.

Extracted Metadata

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

  • 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": "https://w3id.org/workflowhub/workflow-ro-crate#cwl",
  "@type": "ComputerLanguage",
  "name": "Common Workflow Language",
  "alternateName": "CWL",
  "identifier": {
    "@id": "https://w3id.org/cwl/v1.2/"
  },
  "url": {
    "@id": "https://www.commonwl.org/"
  }
}

Galaxy

{
  "@id": "https://w3id.org/workflowhub/workflow-ro-crate#galaxy",
  "@type": "ComputerLanguage",
  "name": "Galaxy",
  "identifier": {
    "@id": "https://galaxyproject.org/"
  },
  "url": {
    "@id": "https://galaxyproject.org/"
  }
}

KNIME

{
  "@id": "https://w3id.org/workflowhub/workflow-ro-crate#knime",
  "@type": "ComputerLanguage",
  "name": "KNIME",
  "identifier": {
    "@id": "https://www.knime.com/"
  },
  "url": {
    "@id": "https://www.knime.com/"
  }
}

Nextflow

{
  "@id": "https://w3id.org/workflowhub/workflow-ro-crate#nextflow",
  "@type": "ComputerLanguage",
  "name": "Nextflow",
  "identifier": {
    "@id": "https://www.nextflow.io/"
  },
  "url": {
    "@id": "https://www.nextflow.io/"
  }
}

Snakemake

{
  "@id": "https://w3id.org/workflowhub/workflow-ro-crate#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.json 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.json",
      "@type": "CreativeWork",
      "about": {
        "@id": "./"
      },
      "conformsTo": [
        { "@id": "https://w3id.org/ro/crate/1.1"},
        { "@id": "https://w3id.org/workflowhub/workflow-ro-crate/1.0"}
      ]
    },
    {
      "@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": "https://w3id.org/workflowhub/workflow-ro-crate#cwl"
      },
      "name": "Example Workflow",
      "image": {
        "@id": "diagram.svg"
      }
    },
    {
      "@id": "diagram.svg",
      "name": "Example Workflow Diagram",
      "@type": [
        "File",
        "ImageObject"
      ]
    },
    {
      "@id": "README.md",
      "@type": "File",
      "about": "./",
      "encodingFormat": "text/markdown"
    },
    {
      "@id": "https://w3id.org/workflowhub/workflow-ro-crate#cwl",
      "@type": "ComputerLanguage",
      "name": "Common Workflow Language",
      "alternateName": "CWL",
      "identifier": "https://w3id.org/cwl/v1.2/",
      "url": "https://www.commonwl.org/"
    }
  ]
}