# Cytomine app JSON descriptor Reference

This section provides a reference for supported JSON descriptor attributes, used to describe Cytomine Apps.

Schema version

This is the cytomine-0.1 specification for Cytomine app JSON descriptor. It is derived from Boutiques-0.5 descriptor schema.

# Name (`name`)

Cytomine app name.

MANDATORY
Type: string

Limitation

When the Cytomine app is released on a trusted source, name must be equals to repository name where prefix has been removed.

If name is MyAwesomeCytomineApp, the repository on the trusted source has to be PREFIXMyAwesomeCytomineApp where PREFIX is the trusted source prefix and can be empty.

# Description (`description`)

Cytomine app description.

Optional
Type: string

# Container image (`container-image`)

MANDATORY to be released on a trusted source
Type: object

# Image (`image`)

Name of the container image for the Cytomine app.

MANDATORY
Type: string

Limitation

When the Cytomine app is released on a trusted source, image must be equals to Cytomine app name in lowercase, prefixed by the trusted source prefix in lowercase and preceded by container image index username.

For a trusted source with prefix S_ and container image index cytomine and a Cytomine app named MyAwesomeApp, the container image image is cytomine/s_myawesomeapp

# Type (`type`)

Type of container image for execution.

MANDATORY
Type: enum("docker","singularity")

Limitation

Type must be singularity because Cytomine currently executes all containers with Singularity. Cytomine will convert Docker images into Singularity ones in background before run it.

# Command line (`command-line`)

A string that describes the Cytomine app command line, where input parameters are identified by keys. At runtime, command-line keys are substituted with flags and values.

MANDATORY
Type: string

# Inputs (`inputs`)

List of Cytomine app parameters.

MANDATORY
Type: list of Input
at least 1 item in the array

# Input ( - )

# Id (`id`)

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

MANDATORY
Type: string

To avoid too much repetition in the descriptor, id value can be inserted automatically in any attribute of the same parameter (input) using placeholders:

Placeholder	Replaced by
`@id`	id value
`@ID`	id value in uppercase

# Value key (`value-key`)

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

Optional
Type: string

# Command line flag (`command-line-flag`)

The Cytomine app parameter option flag, involved in the value-key substitution. Examples: -v, --force, --@id.

Optional
Type: string

# Name (`name`)

A human-readable Cytomine app parameter name. Example: Data file.

MANDATORY
Type: string

# Description (`description`)

A description for the Cytomine app parameter.

Optional
Type: string

# Type (`type`)

The Cytomine app parameter type.

MANDATORY
Type: enum

The value of this property must be one of the following types:

Type	Recognized constraints
`String`	value-choices
`Number`	value-choices, minimum, maximum, integer
`Boolean`
`Date`	value-choices, minimum, maximum
`Domain`	value-choices, uri, uri-print-attribute, uri-sort-attribute
`ListDomain`	uri, uri-print-attribute, uri-sort-attribute

# Optional (`optional`)

Whether if the Cytomine app parameter is optional or not.

Optional
Type: boolean

# Set by server (`set-by-server`)

Whether if the Cytomine app parameter is set by Cytomine server.

Optional
Type: boolean

Usually only true for the 5 mandatory app parameters:

cytomine_host
cytomine_public_key
cytomine_private_key
cytomine_id_project
cytomine_id_software

# Default value (`default-value`)

Default value for the Cytomine app parameter

Optional
Type: consistent with type

# Value choices (`value-choices`)

Permitted choices for parameter value.

Optional
Type: array

Limitation

While this constraint is supported by Cytomine, it is not checked at execution.

# Minimum (`minimum`)

Specify the minimum inclusive value accepted by the app parameter. May only be used with Number type parameter.

Optional
Type: number

Limitation

While this constraint is supported by Cytomine, it is not checked at execution.

# Maximum (`maximum`)

Specify the maximum inclusive value accepted by the app parameter. May only be used with Number type parameter.

Optional
Type: number

Limitation

While this constraint is supported by Cytomine, it is not checked at execution.

# Integer (`integer`)

Specify whether the app parameter has to be an integer. May only be used with Number type parameter.

Optional
Type: boolean

Limitation

While this constraint is supported by Cytomine, it is not checked at execution.

# Uri (`uri`)

If type is Domain or ListDomain, the Cytomine API endpoint providing valid domain(s).

Optional
Type: string

Supported placeholders are:

$currentProject$ replaced by the current Cytomine project ID
$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 images in the project.

# Uri print attribute (`uri-print-attribute`)

If type is Domain or ListDomain, the attribute to print in UI dropdown lists. Ignored otherwise.

Optional
Type: string

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`)

If type is Domain or ListDomain, the attribute used to sort items in UI dropdown lists. Ignored otherwise.

Optional
Type: string

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.

# Schema version (schema-version)

Version of the schema used.

MANDATORY
Type: enum

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

# Complete example

{
  "name": "MyAwesomeApp", 
  "description": "A first awesome Cytomine app.", 
  "container-image": {
    "image": "user/myawesomeapp", 
    "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"
    }, 
  ], 
  "schema-version": "cytomine-0.1"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

← Release a Cytomine App Installation →

# Cytomine app JSON descriptor Reference

# Name (name)

# Description (description)

# Container image (container-image)

# Image (image)

# Type (type)

# Command line (command-line)

# Inputs (inputs)

# Input ( - )

# Id (id)

# Value key (value-key)

# Command line flag (command-line-flag)

# Name (name)

# Description (description)

# Type (type)

# Optional (optional)

# Set by server (set-by-server)

# Default value (default-value)

# Value choices (value-choices)

# Minimum (minimum)

# Maximum (maximum)

# Integer (integer)

# Uri (uri)

# Uri print attribute (uri-print-attribute)

# Uri sort attribute (uri-sort-attribute)

# Schema version (schema-version)

# Complete example

# Name (`name`)

# Description (`description`)

# Container image (`container-image`)

# Image (`image`)

# Type (`type`)

# Command line (`command-line`)

# Inputs (`inputs`)

# Id (`id`)

# Value key (`value-key`)

# Command line flag (`command-line-flag`)

# Name (`name`)

# Description (`description`)

# Type (`type`)

# Optional (`optional`)

# Set by server (`set-by-server`)

# Default value (`default-value`)

# Value choices (`value-choices`)

# Minimum (`minimum`)

# Maximum (`maximum`)

# Integer (`integer`)

# Uri (`uri`)

# Uri print attribute (`uri-print-attribute`)

# Uri sort attribute (`uri-sort-attribute`)