The Application Description is an optional file, that provides additional information about your application. It could be especially important if you share your application with other users and want them to understand better the computation methods you used inside, or if you want to have a description of the methods you use for yourself (e.g. for distinguishing between different versions of the code). 


Contents of the file

File name and format

The Application Description should always have the same name - appDescription.json and has to be placed in the root (main) directory of your application's repository. Otherwise, the system wouldn't be able to locate it.

The format of the file is JSON (pronounced Jason), a commonly used text format for representing objects. When creating and editing the file, you must take care to follow the format rules - e.g. closing brackets, using quotes to enclose field names and text values, otherwise, we will not be able to read the file and display your application. To validate the JSON structure, you can use on-line tools, like https://jsonformatter.curiousconcept.com/ (allows using comments) or https://jsonlint.com/ (features also some tips on how to write your JSON correctly). The full specification of the format can be found at https://www.json.org/.

Structure

Excerpt 1. shows all the possible options that can be specified in the Application Description (appDescription.json) file, with a detail explanation following. Note, the use of curly brackets ('{}') on opening and closing of complex structures (objects) and square brackets ('[]') on opening and closing of listings (arrays). The placement of the double quotes ("") is also important, while the white spaces are ignored. Comments can be added either with double slash ('//') for single-line comments or with sequence /* comment */ for multi-line comment.

{
  "dirName" : "<name of the directory that will be created for the application>",
  "name" : "<full name of the application>",
  "description" : "<longer description of the application>",
  "inputsDescription" : "<description of input files>",
  "resultsDescription" : "<description of result files>",
  "computationalCharacteristic" : "<description of the computational characteristics of the code>",
  "author" : "<author name>",
  "license" : "<licence>",
  "citation" : "<citations>",
  "categories" : [ "<category>" ],
  "keywords":[ "<keyword1>", "<keyword2>" ],
  "references" : {
    "<name of the resource>" : "<link to the resource>"
  },
  "lastUpdate" : "<last modification date>"
}

Excerpt 1. Full structure of the Application Description file

All the possible options are described below. All fields of the Application Description file are optional - if you do not want to use them, just do not add them to the file or put them in comments. If the fields are not specified, the values will be set to defaults or set to empty.

  • dirName - name used for creating application directory, when the application is added to workspace. Usually it is a shortened version of "name" written without spaces (in camel case). It is not recommended to include special characters in this value, some of them are not allowed. If left empty, the name of the application repository will be used as default.
  • name - full name of the application, that will be displayed on the application list. May contain spaces and other special characters. If left empty, the name of the application repository will be used as default.
  • description - longer description of the application. May contain HTML tags, including links. May also include the input or output type name written as ${D__data_type}, where "data_type" is the type of the input or output file - this will be filled with a full name of this data type as set within the EPISODES Platform.
  • inputsDescription - description of the application inputs. May contain HTML tags, including links. It could include listing of the types of inputs (in accordance with the inputs specification within the Application Definition file), but adding more detailed description is advisable. Input types should be written as ${D__data_type}, where "data_type" is the type of the input file.
  • resultsDescription - description of the application results. May contain HTML tags, including links. It could include listing of the types of outputs (in accordance with the outputs specification within the Application Definition file), but adding more detailed description is advisable. Output types should be written as ${D__data_type}, where "data_type" is the type of the output file.
  • computationalCharacteristic - description of the features of the application that might have impact on its computation time or other resources consumption. Should be filled especially if you specified some parameters of the requiredComputationResources option in the Application Definition file as higher than defaults - in such case, explain here in which situations the computation might consume more resources - e.g. larger input files or specific input parameter ranges - as usually with such settings the computation takes longer.
  • author - author of the application, may contain your name, institution and/or project affiliation.
  • license - license used for publishing the application. If you wish your application to be open to other users, include a license here either in text form or a link to an on-line licence (e.g. https://creativecommons.org/licenses/by-sa/4.0/). You might also include it as a LICENCE.txt file in your code repository
  • citation - citations (articles) related to the application (e.g. describing the algorithms it uses). A generic EPISODES Platform citation is always displayed along the ones specified here, therefore, include only citations related solely to this application.
  • categories - list of names of categories to which the application can be assigned. Usually one category is enough, but more can be also used. It is advisable to use the categories already present within the portal. However, you can also add your own.
  • keywords - keywords that match the application. If relevant, use the keywords already defined within the portal, but add also your own, to describe the application best.
  • references - links to additional resources that can be displayed with the application (e.g. user guide). It is a map (dictionary) where the key will be the text of the link and the value will be its web address (URL)
  • lastUpdate - a date when the application was last updated, written in format "dd-MM-yyyy"

Example

Excerpt 2. contains a full description of a sample application (the description is compatible with the application from Example 2 in the Application Definition file configuration guide). Figures 1-3 further show how the description elements are visible inside the EPISODES Platform.

{
  "shortName" : "TestAppVectorOperations",
  "name" : "Test application: Vector Operations",
  "description" : "<p><b>NOTE: This is a test application demonstrating use or e-Research Platform functionalities, not meant for production environment.</b></p><p>Tool for performing simple operations on a given number vector.</p>",
  "inputsDescription" : "${D__double_vector}",
  "resultsDescription" : "${D__double_vector} after performing requested operations",
  "computationalCharacteristic" : "The computation time depends on the input vector, however, should not be longer than several seconds.",
  "author" : "ACC Cyfronet AGH",
  "license" : "Creative Commons Attribution-ShareAlike 4.0 International License: <a href='https://creativecommons.org/licenses/by-sa/4.0/'>https://creativecommons.org/licenses/by-sa/4.0/</a>",
  "citation" : "Author, A., Author, B. et al. (2021). Article title and other details",
  "categories" : [ "Test" ],
  "keywords" : [ "Vectors", "Testing" ],
  "references" : {
    "User Guide" : "https://docs.cyfronet.pl/display/ISDOC/Application+Description+file"
  },
  "lastUpdate" : "24-11-2021"
}

Excerpt 2. A description of a sample app

Figure 1. Elements of the Application Description file displayed on the application list within the EPISODES Platform

Figure 2. Elements of the Application Description file displayed on the application information page within the EPISODES Platform

Figure 3. Elements of the Application Description file displayed with the application in workspace within the EPISODES Platform




Related Documents