Page tree
Skip to end of metadata
Go to start of metadata

Boutiques descriptor



Cytomine schema reference

This section provides a reference for JSON descriptor attributes. In order to fulfill Cytomine requirements, some adaptations have been made to official Boutiques schema (version 0.5). A forked schema has been design and is currently in its version 0.1 (cytomine-0.1).

Cytomine nomenclature is a bit different than Boutiques one. Here is a conversion table that can be useful in this section.

Boutiques wordCytomine word
toolsoftware
inputsoftware parameter
input IDsoftware parameter name
input namesoftware parameter human name
input optionalinverse of software parameter required

Name (name) 

Tool (software) name.

name

  • is required
  • type: string
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Current Cytomine limitation: Name must be equals to repository name where prefix has been removed.

Example: Repository = "S_MySoftware" → descriptor name = "MySoftware"

Description (description)

Tool (software) description.

description

  • is optional
  • type: string
  • defined by Boutiques schema 0.5 (→ required)
  • updated by Cytomine schema 0.1 (→ optional)
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Container image (container-image)

container-image

  • is required
  • type: object
  • defined by Boutiques schema 0.5 (→ optional)
  • update by Cytomine schema 0.1 (→ required)
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Image (image)

Name of an image where the tool is installed and configured.

image

  • is required
  • type: string
  • defined by Boutiques schema 0.5 
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Current Cytomine limitation: Image name must be equals to lowercase repository name is VCS (eg. Github, including prefix) preceded by image index (eg. Docker Hub) username.

Example: Repository = "S_MySoftware" and DockerHub username = "cytomineuliege" → image = "cytomineuliege/s_mysoftware"

Index (index)

Optional index where the image is available, if not the standard location (Docker hub docker.io).

index

  • is optional
  • type: string
  • defined by Boutiques schema 0.5 
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

Type (type)

Type of image for execution.

type

  • is required
  • type: enum("docker", "singularity")
  • defined by Boutiques schema 0.5 
  • updated  by Cytomine schema 0.1 (→ remove docker)
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Cytomine limitation: Type must be "singularity" because Cytomine executes all containers with Singularity. Cytomine will convert Docker images into Singularity ones in background before run it. Docker could be re-introduced in future.

Command line (command-line)

A string that describes the tool command line, where input and output values are identified by "keys". At runtime, command-line keys are substituted with flags and values.

command-line

  • is required
  • type: string
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Inputs (inputs)

List of tool inputs (software parameters).

inputs

  • is required
  • type: object[]
  • at least 1 items in the array
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Input ( - )

Id (id)

A short, unique, informative identifier containing only alphanumeric characters and underscores. Typically used to generate variable names. Example: "data_file".

id

  • is required
  • type: string
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Id value can be inserted automatically in any attribute of the same input using placeholders:

PlaceholderReplaced by
@idid value
@IDid value in uppercase

Value key (value-key)

A string contained in command-line, substituted by the input value and/or flag at runtime. Example: [@ID]

value-key

  • is optional
  • type: string
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Command line flag (command-line-flag)

Option flag of the input, involved in the value-key substitution. Inputs of type "Flag" have to have a command-line flag. Examples: -v, --force, --@id.

command-line-flag

  • is optional
  • type: string
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Name (name)

A human-readable input name. Example: 'Data file'.

name

  • is required
  • type: string
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Description (description)

Input description.

description

  • is optional
  • type: string
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Type (type)

Input type.

type

  • is required
  • type: string
  • defined by Boutiques schema 0.5
  • updated by Cytomine schema 0.1
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

The value of this property must be equal to one of the following type:

TypeRecognized constraintsRemark
Stringvalue-choices
Numbervalue-choices, minimum, maximum, integer
Boolean
Cytomine specific ("Flag" is used in Boutiques)
Datevalue-choices, minimum, maximumCytomine specific
Domainvalue-choices, uri, uri-print-attribute, uri-sort-attributeCytomine specific
ListDomainuri, uri-print-attribute, uri-sort-attribute

Cytomine specific

DEPRECATED IN UPCOMING RELEASE WHEN "LIST" WILL BE SUPPORTED

Optional (optional)

True if input is optional.

optional

  • is optional
  • type: boolean
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Set by server (set-by-server)

True if input is set by Cytomine server.

set-by-server

  • is optional
  • type: boolean
  • defined by Cytomine schema 0.1
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Default value (default-value)

Default value of the input, used by the tool when no option is specified.

default-value

  • is optional
  • type: consistent with type
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Value choices (value-choices)

Permitted choices for input value. May not be used with the Flag type.

value-choices

  • is optional
  • type: array
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Current Cytomine limitation: This constraint is well saved in database but not checked at execution.

Minimum (minimum)

Specify the minimum value of the input (inclusive). May only be used with Number type inputs.

minimum

  • is optional
  • type: number
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Current Cytomine limitation: This constraint is well saved in database but not checked at execution.

Maximum (maximum)

Specify the maximum value of the input (inclusive). May only be used with Number type inputs.

maximum

  • is optional
  • type: number
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Current Cytomine limitation: This constraint is well saved in database but not checked at execution.

Integer (integer)

Specify whether the input should be an integer. May only be used with Number type inputs.

integer

  • is optional
  • type: boolean
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Current Cytomine limitation: This constraint is well saved in database but not checked at execution.

Uri (uri)

Specify the URI relative to a collection of Cytomine objects. May only be used with Domain and ListDomain type inputs. Improve user exeperience in Cytomine web interface.

uri

  • is optional
  • type: string
  • defined by Cytomine schema 0.1
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Supported placeholders:

  1. $currentProject$ replaced by the current Cytomine project ID
  2. $currentOntology$ replaced by the current Cytomine ontology ID

Examples:

  • /api/ontology/$currentOntology$/term.json provides the list of terms in the project's ontology
  • /api/project/$currentProject$/imageinstance.json provides the list of image instance in the project.

Uri print attribute (uri-print-attribute)

Specify the domain attribute to print in the collection of Cytomine objects provided by uri. May only be used with Domain and ListDomain type inputs. Refer to API documentation for acceptable values.

uri-print-attribute

  • is optional
  • type: string
  • defined by Cytomine schema 0.1
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Example:

  • uri="/api/project/$currentProject$/imageinstance.json" and uri-print-attribute="originalFilename" shows the list of images in the projects by original filenames.

Uri sort attribute (uri-sort-attribute)

Specify the domain attribute used to sort the collection of Cytomine objects provided by uri. May only be used with Domain and ListDomain type inputs. Refer to API documentation for acceptable values.

uri-print-attribute

  • is optional
  • type: string
  • defined by Cytomine schema 0.1
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

Example:

  • uri="/api/project/$currentProject$/imageinstance.json"uri-print-attribute="originalFilename" and uri-sort-attribute="created" shows the list of images in the projects by printing original filenames and sorted by creation date.

List (list)

True if input is a list of value. An input of type "Boolean" cannot be a list.

list

  • is optional
  • type: boolean
  • defined by Boutiques schema 0.5
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

Schema version (schema-version)

Version of the schema used.

schema-version

  • is required
  • type: enum
  • defined by Boutiques schema 0.5
  • SUPPORTED IN CYTOMINE-0.1 SCHEMA

To be supported by Cytomine, schema version must be cytomine-0.1

Suggested resources (suggested-resources)

suggested-resources

  • is optional
  • type: object
  • defined by Boutiques schema 0.5
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

CPU cores (cpu-cores)

The requested number of cpu cores to run the described application

cpu-cores

  • is optional
  • type: integer
  • defined by Boutiques schema 0.5
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

Disk space (disk-space)

The requested number of GB of storage to run the described application

disk-space

  • is optional
  • type: number
  • defined by Boutiques schema 0.5
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

Nodes (nodes)

The requested number of nodes to spread the described application across

nodes

  • is optional
  • type: integer
  • defined by Boutiques schema 0.5
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

RAM (ram)

The requested number of GB RAM to run the described application

ram

  • is optional
  • type: number
  • defined by Boutiques schema 0.5
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

Walltime estimate (walltime-estimate)

Estimated wall time of a task in seconds.

walltime-estimate

  • is optional
  • type: number
  • defined by Boutiques schema 0.5
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

Tags (tags)

A set of key-value pairs specifying tags describing the pipeline. The tag names are open, they might be more constrained in the future.

tags

  • is optional
  • type: object
  • defined by Boutiques schema 0.5
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

Author (author)

Tool author name(s).

author

  • is optional
  • type: string
  • defined by Boutiques schema 0.5
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

URL (url)

Tool URL.

url

  • is optional
  • type: string
  • defined by Boutiques schema 0.5
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

Tool DOI (tool-doi)

DOI of the tool (not of the descriptor).

tool-doi

  • is optional
  • type: string
  • defined by Boutiques schema 0.5
  • PLANNED SUPPORT IN CYTOMINE-0.2 SCHEMA

Custom (custom) [not supported]

custom

  • is optional
  • type: object
  • defined by Boutiques schema 0.5
  • NO SUPPORT IN CYTOMINE SCHEMA

DOI (doi) [not supported]

DOI of the descriptor (not of the tool itself).

doi

  • is optional
  • type: string
  • defined by Boutiques schema 0.5
  • NO SUPPORT IN CYTOMINE SCHEMA

Environment variables (environment-variables) [not supported]

An array of key-value pairs specifying environment variable names and their values to be used in the execution environment.

environment-variables

  • is optional
  • type: object[]
  • at least 1 items in the array
  • defined by Boutiques schema 0.5
  • NO SUPPORT IN CYTOMINE SCHEMA

Error codes (error-codes) [not supported]

An array of key-value pairs specifying exit codes and their description. Can be used for tools to specify the meaning of particular exit codes. Exit code 0 is assumed to indicate a successful execution.

error-codes

  • is optional
  • type: object[]
  • at least 1 items in the array
  • defined by Boutiques schema 0.5
  • NO SUPPORT IN CYTOMINE SCHEMA

Groups (groups) [not supported]

Sets of identifiers of inputs, each specifying an input group.

groups

  • is optional
  • type: object[]
  • at least 1 items in the array
  • defined by Boutiques schema 0.5
  • NO SUPPORT IN CYTOMINE SCHEMA

Invocation schema (invocation-schema) [not supported]

invocation-schema

  • is optional
  • type: object
  • defined by Boutiques schema 0.5
  • NO SUPPORT IN CYTOMINE SCHEMA

Output files (output-files) [not supported]

output-files

  • is required
  • type: object[]
  • at least 1 items in the array
  • defined by Boutiques schema 0.5
  • NO SUPPORT IN CYTOMINE SCHEMA

Shell (shell) [not supported]

Absolute path of the shell interpreter to use in the container (defaults to /bin/sh).

shell

  • is optional
  • type: string
  • defined by Boutiques schema 0.5
  • NO SUPPORT IN CYTOMINE SCHEMA

Tests (tests) [not supported]

tests

  • is optional
  • type: object[]
  • at least 1 items in the array
  • defined by Boutiques schema 0.5
  • NO SUPPORT IN CYTOMINE SCHEMA

Tool version (tool-version) [not supported]

Tool version.

tool-version

  • is required
  • type: string
  • defined by Boutiques schema 0.5
  • NO SUPPORT IN CYTOMINE SCHEMA


Complete example

{
  "name": "tool name", 
  "description": "tool description", 
  "container-image": {
    "image": "user/image", 
    "index": "docker://", 
    "type": "singularity"
  }, 
  
  "command-line": "echo [CYTOMINE_HOST] [CYTOMINE_PUBLIC_KEY] [CYTOMINE_PRIVATE_KEY] [CYTOMINE_ID_PROJECT] [CYTOMINE_ID_SOFTWARE] [PARAM1] [PARAM2] [PARAM3] [PARAM4] [PARAM5] [PARAM6] [PARAM7] [PARAM8] [CYTOMINE_VERBOSITY]", 
  "inputs": [
    {
      "id": "cytomine_host", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "Cytomine host", 
      "description": "Mandatory to communicate with Cytomine; automatically filled by server",
      "set-by-server": true,
      "optional": false, 
      "type": "String"
    },
    {
      "id": "cytomine_public_key", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "Cytomine public key", 
      "description": "Mandatory to communicate with Cytomine; automatically filled by server",
      "set-by-server": true,
      "optional": false, 
      "type": "String"
    },
    {
      "id": "cytomine_private_key", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "Cytomine public key", 
      "description": "Mandatory to communicate with Cytomine; automatically filled by server",
      "set-by-server": true,
      "optional": false, 
      "type": "String"
    },
    {
      "id": "cytomine_id_project", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "Cytomine project ID", 
      "description": "Mandatory to communicate with Cytomine; automatically filled by server",
      "set-by-server": true,
      "optional": false, 
      "type": "Number"
    },
    {
      "id": "cytomine_id_software", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "Cytomine software ID", 
      "description": "Mandatory to communicate with Cytomine; automatically filled by server",
      "set-by-server": true,
      "optional": false, 
      "type": "Number"
    },
    {
      "id": "cytomine_verbosity", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "Log verbosity level", 
      "description": "Type and values depends on your software implementation, not set by server and must be optional",
      "optional": true, 
      "type": "String"
    },
    {
      "id": "param1", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "The first parameter (human readable name)", 
      "description": "A string without restriction and optional",
      "optional": true, 
      "type": "String", 
      "default-value": "hello"
    }, 
    {
      "id": "param2", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "The second parameter (human readable name)", 
      "description": "A string choice among possibilities",
      "optional": false, 
      "type": "String", 
      "values-choice": ["A", "B"],
      "default-value": "A"
    }, 
    {
      "id": "param3", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "The third parameter (human readable name)", 
      "description": "A number without restriction",
      "optional": false, 
      "type": "Number"
    }, 
    {
      "id": "param4", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "The fourth parameter (human readable name)", 
      "description": "A number between 0 (inclusive) and 100 (inclusive)",
      "optional": false, 
      "type": "Number", 
      "minimum": "0",
      "maximum": "100"
    }, 
    {
      "id": "param5", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "The fifth parameter (human readable name)", 
      "description": "A number which is an integer",
      "optional": false, 
      "type": "Number", 
      "integer": true
    }, 
    {
      "id": "param6", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "The sixth parameter (human readable name)", 
      "description": "A number choice among possibilities",
      "optional": false, 
      "type": "Number", 
      "values-choice": [10, 20, 30]
    }, 
    {
      "id": "param7", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "The seventh parameter (human readable name)", 
      "description": "A boolean",
      "optional": false, 
      "type": "Boolean"
    }, 
    {
      "id": "param8", 
      "value-key": "[@ID]",
      "command-line-flag": "--@id", 
      "name": "The eigth parameter (human readable name)", 
      "description": "A Cytomine domain; here an image instance in the current project",
      "optional": false, 
      "type": "Domain",
      "uri": "/api/project/$currentProject$/imageinstance.json",
      "uri-print-attribute": "instanceFilename",
      "uri-sort-attribute": "created"
    }, 
  ], 

  "suggested-resources": {
    "cpu-cores": 1, 
    "ram": 1, 
    "walltime-estimate": 60
  }, 
  "tags": {
    "foo": "bar", 
    "purpose": "testing", 
    "status": "example"
  },

  "schema-version": "cytomine-0.1"
}
  • No labels