App Metadata
Last updated
Was this helpful?
Last updated
Was this helpful?
The file dxapp.json
is a DNAnexus application metadata file. Its presence in a directory tells DNAnexus tools that this directory contains DNAnexus app source code. The file's format is defined by convention and operationally by DNAnexus tools that use it (usually invoked through dx build
and dx build --create-app
).
The format of the file closely resembles that of the corresponding calls to and , except for some differences as noted below. Fields found in dxapp.json
but not recognized by the build tools are passed through to the API methods.
The next section is a detailed example showing most of the commonly used fields.
The following lists the contents of an example dxapp.json
to be provided in a directory for use with the dx build
command. For fields that are marked for apps only, it is harmless to provide them when building applets; they will simply only take effect when building apps.
Note that comments as shown below are not valid in the JSON format but are provided here for easy reference.
Other options for the /applet/new
and /app/new
calls, such as specifying in which project or folder to create an applet, are populated via command-line flags of dx build
.
name
The name
string The unique name of the applet / app. The name
can have lower case letters, numbers, -
, and _
but cannot have spaces.
Example:
title
title
string (optional) A human-readable name of the app(let). If published as an app, this name will be shown on the Apps page and as the default job name.
Example:
summary
summary
string (optional) A one-liner description of the app(let). If published as an app, this summary will be displayed under the app name on the Apps page.
Example:
description
description
string (optional) Longer description of what the app(let) does. If not provided, dx build will inline the Readme.md file, if available.
Example:
developerNotes
developerNotes
string (optional) Detailed notes covering extra details. If not provided, dx build
will inline the Readme.developer.md
file, if available.
Example:
details
(Developer and Contact Info, and Other Metadata)details
string (optional) This can contain arbitrary metadata, but there are some key/value pairs that are recognized as conventions by the website when rendering your app, e.g. for displaying contact information. Recognized metadata fields include the following:
Author contact information
Upstream executable version number (i.e. bwa-mem 0.7.12)
Upstream author name
URL for app executable
Upstream licenses
Change Log
Citations for papers
Example:
dxapi
dxapi
string (optional) The version of the API that your app uses.
Example:
version
version
string Apps only: The version of the app to be built identifing each build of your app. This version number must be unique from all other versions of the app (published or not).
Example:
categories
(User-Browseable Categories)You can specify any categories you wish for your app in the "categories" field of the dxapp.json. However, the following categories are specially recognized by DNAnexus, and authorized users of your app can use them to browse for your app in the App Store if you specify any of them:
Annotation
Assembly
Debugging
Export
Import
Mappings Manipulation
Read Manipulation
Read Mapping
Reports
RNA-Seq
Statistics
Structural Variation
Variation Calling
Example:
inputSpec
and outputSpec
runSpec
(Entry Point and Dependencies)The runSpec
field specifies your app's entry and the interpreter used to evaluate it:
In the above example, the "runSpec.file" parameter provides the path to a Python file that contains your application logic.
In this case, we've provided Python code (code.py
) that uses the DNAnexus Python 3 execution template (indicated in the interpreter
field). This template takes care of parsing your app's input from the DNAnexus execution environment, handling possible errors, and saving your app's output. See the example applications for examples of the entry point Python function signatures.
access
field (App Permissions)In order to both make reproducibility guarantees feasible and protect user privacy, apps are generally heavily restricted in what data they can read and write. Apps may request relaxation of these restrictions.
authorizedUsers
field (Who Can Access Your App)You can specify who can describe and run your app by providing a list of users. The default access list is the empty list []
, which indicates that no one except the developers of the app can find and run your app, even if it has been published. You may provide a list of users and/or organizations here to grant them access the app.
Note: the access list is shared for all past and future versions of the app but can be modified at any time. If you need to create another version of your app which has a different access list, you will need to publish it separately under a different name.
You can also edit the list of authorized users after you've built and published an app by using the dx add users
and dx remove users
commands. However, if you (or another developer) rebuilds the app with authorizedUsers
in the dxapp.json
file, the access list will be overwritten to match the one found in the file.
regionalOptions
field (Which Regions the App Can Be Run In)The values associated with each key are themselves mappings. In the most basic usage, you can specify an empty mapping for each region. This is generally sufficient to allow apps that don't use certain advanced features to be run in multiple regions.
bundledDepends
list bundled dependencies for the corresponding region. For the syntax of this field, see the discussion of bundledDepends
in the run specification.
assetDepends
list asset dependencies for the corresponding region. See the assetDepends
field above for the syntax of this field.
resources
string or array of strings Either a string containing the ID of a project which will be snapshotted into a resources container, or an array of data object IDs, which will all be cloned into the root folder of the resources container. All specified objects must reside in the specified region and will be available to the app when it is run in that region.
If you specify a value for a key, say "systemRequirements", you must do so in all regions, and you may not specify the same key in the run specification.
If the applet is into an app, then its ID will be of the form app-[name]/[version]
. An app's name cannot be changed across versions.
We recommend following the conventions for numbering the versions of your app. Semantic Versioning also specifies how you should change the version number for various kinds of updates to your app (that is, bug-fix only, backwards compatible, or backwards incompatible). Using the Semantic Versioning guidelines will help users and other developers to understand when it is safe to move between different versions of your app.
JSON array containing the specifications for each input to the app. These fields are required for apps and highly recommended when developing applets. The full documentation for specifying an input or output specification can be found .
If you do choose to exclude an input (output) specification for an applet (i.e. one or more of the keys inputSpec
and outputSpec
is missing), this means that the system will perform no checking on the input (output) provided to (returned by) the applet, respectively. Note, however, that applets that do not have both an input and output specification cannot be added as a stage in a .
For more details about execution templates and running code in the execution environment, see the .
The full documentation on the options that can be requested can be found .
See also the Guide for more information about the permissions available and their implications.
You can specify what regions the app can be run in, and specify advanced options that control the app's behavior in multiple regions. The regionalOptions
field should be a mapping with keys corresponding to each region in which the app should be runnable. (A region is given by a string like "aws:us-east-1"; see for more information about regions.) If you don't specify this field, the app will be enabled in only one region: the region of your project context when the app is built.
For apps that make use of , additional resources, or specify that they should run on specific instance types, each value of regionalOptions
may contain the following keys and values:
mapping Request specific instance types and (optional) define a clusterSpec for some of the entry points of the app when it is run in the corresponding region.