App Metadata

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 (invoked through dx build and dx build --create-app).

The format of the file resembles that of the corresponding calls to /applet/new and /app/new, 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.

Examples

Three examples at different complexity levels:

Minimal - Getting started or prototyping
Basic - Production apps with standard requirements
Comprehensive - Advanced features (multi-region, clusters, complex permissions)

Deprecated fields: runSpec.systemRequirements and top-level resources are deprecated. Define these settings in regionalOptions.<region> instead. For migration details, see Migration from Deprecated Fields.

This example demonstrates commonly used dxapp.json fields including input and output type constraints, multi-region deployment, asset and bundled dependencies, execution and timeout policies, cluster specifications, GPU/FPGA drivers, and access control. This is not an exhaustive list of all available fields. See the Specification section below for root-level field documentation and I/O and Run Specifications for a complete API reference.

Comments shown below are for reference only and are not valid in the JSON format.

dxapp.json

{
  // Required: Simple name. Globally unique identifier for apps. Immutable across versions. Allowed: a-z, 0-9, _, -
  "name": "mapper",
  // Recommended: Human-readable name (shown in the UI)
  "title": "Simple Read Mapper",
  // Recommended: One-line description of what the app(let) does
  "summary": "Maps reads to a genome",
  // Optional: Detailed description. If omitted, dx build inlines the Readme.md file if available
  "description": "This app maps sequencing reads to a reference genome using BWA-MEM...",
  // Optional: Technical notes. If omitted, dx build inlines the Readme.developer.md file if available
  "developerNotes": "Additional notes for developers maintaining this app...",
  // Optional: Arbitrary metadata
  "details": {
    "contactEmail": "[email protected]"
  },
  // Recommended: DNAnexus API version
  "dxapi": "1.0.0",
  // Apps — Required. Semantic versioning (MAJOR.MINOR.PATCH) is recommended.
  "version": "0.0.1",
  // Optional: Recognized or custom categories for Tools Library
  "categories": ["Read Mapping"],
  // Apps — Required; Applets — Recommended: Input definitions (see I/O and Run Specifications for details)
  "inputSpec": [
    {
      // Required: Parameter name (alphanumeric/underscore; starts with letter/underscore)
      "name": "reads",
      // Required: Data type
      "class": "array:file",
      // Optional: Type constraint (e.g., specific file ontology)
      "type": "Reads",
      // Optional: Filename patterns (e.g. "*.txt"). For data objects, use a mapping with "name", "pointer_class", and "tag"
      "patterns": ["*.fastq", "*.fastq.gz"],
      // Optional: Display name in UI
      "label": "Sequencing Reads",
      // Optional: Tooltip description
      "help": "Input FASTQ files containing sequencing reads",
      // Optional: Predefined values to populate the UI (does not restrict input like "choices")
      "suggestions": [
        {
          "name": "DNAnexus Reference Genomes",
          "project": "project-BQpp3Y804Y0xbyG4GJPQ01xv",
          "path": "/"
        },
        {
          "name": "GRCh38 BWA Index",
          "value": {"$dnanexus_link": "file-xxxx"}
        }
      ],
    },
    {
      "name": "reads_type",
      "class": "string",
      "default": "paired-end",
      // Optional: Mark as omittable (default is false)
      "optional": true,
      // Optional: Restrict input to specific values
      "choices": ["single-end", "paired-end"],
      // Optional: Group parameters in the UI
      "group": "Advanced Options"
    }
  ],
  // Apps — Required; Applets — Recommended: Output definitions
  "outputSpec": [
    {
      "name": "mappings",
      "class": "file",
      "patterns": ["*.bam"],
      "help": "Mapped reads in BAM format"
    }
  ],
  // Required: How to run the executable
  "runSpec": {
    // Required: Interpreter ("bash" or "python3")
    "interpreter": "bash",
    // Required (or "code"): Path to the entry point script (inlined during build)
    "file": "src/mapper.sh",
    // Required: OS distribution (only "Ubuntu" supported)
    "distribution": "Ubuntu",
    // Required: Ubuntu version ("20.04" or "24.04")
    "release": "24.04",
    // Required: Execution environment version
    "version": "0",
    // Optional: Use on-demand instance for the head job, preserving the specified priority for the rest of the execution tree
    "headJobOnDemand": true,
    // Optional: Restart behavior — "all" or "master" (default)
    "restartableEntryPoints": "all",
    // Optional: Package dependencies (installed at runtime). Not recommended for production: package versions can change between job executions, causing inconsistent behavior. Prefer assetDepends or bundledDepends for reproducible builds.
    "execDepends": [
      {
        // Required: Package name
        "name": "bwa",
        // Optional: Package manager. Supported values: "apt", "pip3", "pip", "gem", "cpan", "cran", "git"
        "package_manager": "apt"
      }
    ],
    // Optional: Asset dependencies - pre-built asset bundles (automatically unpacked)
    "assetDepends": [
      {
        // Method 1: Reference by record ID
        "id": "record-Bq320600kXGxY7PyB43GZ69j"
      },
      {
        // Method 2: Reference by name. Required: name, project, version. Optional: folder
        "name": "bwa_asset",
        "project": "project-Bq1pqV00kXGgzp45j4jGyYY7",
        "version": "1.0.0",
        "folder": "/assets"
      }
    ],
    // Optional: Bundled dependencies - raw file archives
    "bundledDepends": [
      {
        // Required: Filename
        "name": "resources.tar.gz",
        // Required: File object reference
        "id": {"$dnanexus_link": "file-xxxx"}
      }
    ],
    // Optional: Options governing job restart policy
    "executionPolicy": {
      // Optional: Restart counts per error type
      "restartOn": {
        "ExecutionError": 2,
        "UnresponsiveWorker": 3,
        // All other restartable errors
        "*": 1
      },
      // Optional: Global restart limit (0-9; default 9)
      "maxRestarts": 5
    },
    // Optional: Inherit parent job's restartOn policy (default false)
    "inheritParentRestartOnPolicy": false,
    // Optional: Execution time limits per entry point (default 30 days)
    "timeoutPolicy": {
      // "main" is the name of the entry point that is called when this executable is run
      "main": {
        "days": 2,
        "hours": 12
      },
      // "process" is the name of an entry point (used when spawning a new job via /job/new that runs the function called "process")
      "process": {
        "hours": 6,
        "minutes": 30
      },
      // Fallback for all other entry points
      "*": {
        "hours": 4
      }
    }
  },
  // Optional: Disable Smart Reuse. Default is false (reuse allowed). Can be overridden at runtime.
  "ignoreReuse": true,
  // Apps only — Optional: Expose source code to the app's authorized users and developers
  "openSource": true,
  // Optional: Externally expose jobs to the internet via HTTPS proxy at https://job-xxxx.dnanexus.cloud/
  "httpsApp": {
    // Required: Exposed ports
    "ports": [443, 8080, 8081],
    // Required: Minimum project access level (VIEW, CONTRIBUTE, ADMINISTER, NONE)
    "shared_access": "VIEW"
  },
  // Optional: Request additional permissions (default: restricted)
  "access": {
    // Optional: Allowed domains or "*" for unrestricted internet access
    "network": ["*"],
    // Optional: Access to the launch project. Defaults to NONE for apps and VIEW for applets
    "project": "CONTRIBUTE",
    // Optional: Access to all user projects
    "allProjects": "VIEW",
    // Optional: Act as developer (create/modify apps, access unpublished apps)
    "developer": true,
    // Optional: Create new projects
    "projectCreation": true
  },
  // Apps only — Recommended: Users who can modify/publish the app
  "developers": ["user-alice"],
  // Apps only — Recommended: Users/Orgs who can run the app (use "PUBLIC" for public apps). For applets, access is determined by access to the project containing the applet.
  "authorizedUsers": ["org-example_lab"],
  // Recommended: Region-specific configuration.
  // For apps, specify all regions where the app can run and region-specific settings (systemRequirements, bundledDepends, assetDepends, resources).
  // For applets, specify systemRequirements for the build region.
  "regionalOptions": {
    // Region key (see Regions documentation for valid identifiers)
    "aws:us-east-1": {
      // Region-specific instance types and drivers
      "systemRequirements": {
        "main": {"instanceType": "mem2_ssd1_x4"},
        // Subjob entry point on a GPU instance
        "process": {
          "instanceType": "mem3_ssd2_gpu_x8",
          "nvidiaDriver": "R535"
        },
        // Subjob entry point on an FPGA instance
        "process_fpga": {
          "instanceType": "mem3_ssd2_fpga1_x24",
          "fpgaDriver": "edico-1.4.9.2"
        },
        // Subjob entry point with dynamic instance type selection
        "analyze": {
          // Optional: Tries each instance type in order until one is available
          "instanceTypeSelector": {
            "allowedInstanceTypes": ["mem1_ssd1_x4", "mem1_ssd1_x8", "mem2_ssd1_x4"]
          }
        },
        // Defaults for all other entry points, including a cluster
        "*": {
          "instanceType": "mem3_ssd1_x4",
          // Optional: Request a cluster of instances
          "clusterSpec": {
            // Required: "dxspark", "apachespark", or "generic"
            "type": "dxspark",
            // Required for dxspark/apachespark: Spark version
            "version": "3.2.3",
            // Optional: Cluster size (min 1) including the driver node
            "initialInstanceCount": 3,
            // Optional: Ports and port-ranges to open for communication between nodes in the cluster
            "ports": "1000, 1100-1200",
            // Optional: Script to run on all nodes before running app code
            "bootstrapScript": "./bootstrap.sh"
          }
        }
      },
      // Region-specific bundled dependencies
      "bundledDepends": [
        {"name": "bundle.tar.gz", "id": {"$dnanexus_link": "file-xxxx"}}
      ],
      // Region-specific asset bundle dependencies
      "assetDepends": [
        {
          "name": "bwa_asset",
          "project": "project-Bq1pqV00kXGgzp45j4jGyYY7",
          "version": "1.0.0"
        }
      ]
    },
    "azure:westus": {
      "systemRequirements": {
        "main": {"instanceType": "azure:mem2_ssd1_x4"}
      },
      "bundledDepends": [
        {"name": "bundle.tar.gz", "id": {"$dnanexus_link": "file-zzzz"}}
      ],
      "assetDepends": [
        {"id": "record-yyyy"}
      ]
    }
  }
}

This example shows commonly used fields for a typical analysis app with reasonable production practices.

Use this for: Most production apps with moderate complexity.

dxapp.json

{
  "name": "mapper",
  "title": "Simple Read Mapper",
  "summary": "Maps reads to a genome",
  "description": "This app maps sequencing reads to a reference genome using BWA-MEM...",
  "dxapi": "1.0.0",
  "version": "0.0.1",
  "categories": ["Read Mapping"],
  "details": {
    "contactEmail": "[email protected]",
    "upstreamVersion": "0.7.17",
    "upstreamAuthor": "Heng Li",
    "upstreamUrl": "https://github.com/lh3/bwa",
    "upstreamLicenses": ["GPLv3"],
    "citations": ["doi:10.1093/bioinformatics/btp324"]
  },
  "inputSpec": [
    {
      "name": "reads",
      "class": "array:file",
      "patterns": ["*.fastq", "*.fastq.gz"],
      "help": "Input FASTQ files containing sequencing reads",
      "optional": false
    },
    {
      "name": "genomeindex_targz",
      "label": "BWA reference genome index",
      "class": "file",
      "patterns": ["*.bwa-index.tar.gz"],
      "help": "Pre-built BWA reference index packaged as tar.gz",
      "suggestions": [
        {
          "name": "DNAnexus Reference Genomes",
          "project": "project-BQpp3Y804Y0xbyG4GJPQ01xv",
          "path": "/"
        }
      ],
      "optional": false
    },
    {
      "name": "reads_type",
      "class": "string",
      "default": "paired-end",
      "choices": ["single-end", "paired-end"],
      "group": "Advanced Options"
    }
  ],
  "outputSpec": [
    {
      "name": "mappings",
      "class": "file",
      "patterns": ["*.bam"],
      "help": "Mapped reads in BAM format"
    }
  ],
  "runSpec": {
    "interpreter": "bash",
    "file": "src/mapper.sh",
    "distribution": "Ubuntu",
    "release": "24.04",
    "version": "0",
    "assetDepends": [
      {
        "name": "bwa_asset",
        "project": "project-Bq1pqV00kXGgzp45j4jGyYY7",
        "version": "1.0.0"
      }
    ]
  },
  "access": {
    "network": ["*"],
    "project": "CONTRIBUTE"
  },
  "regionalOptions": {
    "aws:us-east-1": {
      "systemRequirements": {
        "main": {"instanceType": "mem2_ssd1_x4"}
      }
    },
    "azure:westus": {
      "systemRequirements": {
        "main": {"instanceType": "azure:mem2_ssd1_x4"}
      }
    }
  }
}

The simplest dxapp.json file requires only the name and runSpec fields. Apps also require version, inputSpec, and outputSpec to build successfully.

Use this for: Quick applet prototyping, testing execution environments.

dxapp.json

{
  "name": "my_tool",
  "runSpec": {
    // Required: Interpreter ("bash" or "python3")
    "interpreter": "bash",
    // Required (or "code"): Path to the entry point script
    "file": "src/my_tool.sh",
    // Required: OS distribution (only "Ubuntu" supported)
    "distribution": "Ubuntu",
    // Required: Ubuntu version ("20.04" or "24.04")
    "release": "24.04",
    // Required: Execution environment version
    "version": "0"
  }
}

For apps, add these required fields:

dxapp.json

{
  "name": "my_tool",
  "version": "0.0.1",
  "inputSpec": [],
  "outputSpec": [],
  "runSpec": {
    // Required: Interpreter ("bash" or "python3")
    "interpreter": "bash",
    // Required (or "code"): Path to the entry point script
    "file": "src/my_tool.sh",
    // Required: OS distribution (only "Ubuntu" supported)
    "distribution": "Ubuntu",
    // Required: Ubuntu version ("20.04" or "24.04")
    "release": "24.04",
    // Required: Execution environment version
    "version": "0"
  }
}

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.

Specification

This section focuses on practical dxapp.json usage. For canonical API field definitions and constraints, use /applet/new, /app/new, and the I/O and Run Specifications reference.

`name`

The name field is a string (required) containing the unique name of the applet or app. The name can have lower case letters, numbers, -, and _ but cannot have spaces.

If the applet is published into an app, then its ID is of the form app-[name]/[version]. An app's name cannot be changed across versions.

Example:

{
  "name": "bwa_mem_fastq_read_mapper",
}

`title`

title string (optional) A human-readable name of the app(let). If published as an app, this name is shown on the Apps page and as the default job name.

Example:

{
  "title": "BWA-MEM FASTQ Read Mapper",
}

`summary`

summary string (optional) A one-liner description of the app(let). If published as an app, this summary is displayed under the app name on the Apps page.

Example:

{
  "summary": "Maps FASTQ reads to a reference genome with the BWA-MEM algorithm.",
}

`description`

description string (optional) Longer description of what the app(let) does. If not provided, dx build includes the Readme.md file content, if available.

Example:

{
  "description": "This app maps FASTQ reads to a reference genome ... inputs ...",
}

`developerNotes`

developerNotes string (optional) Detailed notes covering extra details. If not provided, dx build includes the Readme.developer.md file content, if available.

Example:

{
  "developerNotes": "...",
}

`details`

details mapping (optional) Contains arbitrary metadata, but there are some key/value pairs that are recognized as conventions by the DNAnexus Platform when rendering your app. For example, for displaying contact information. You can add any custom key-value pairs beyond the recognized fields.

Example:

{
  // Arbitrary metadata for your app or applet.
  "details": {
    // Contact email for the app/applet author or maintainer.
    "contactEmail": "[email protected]",
    // Citations for papers; DOIs or bibliographic strings are accepted.
    "citations": [
      "doi:10.1093/bioinformatics/btp352"
    ],
    // Version of the upstream executable/tool (e.g., "bwa-mem 0.7.12").
    "upstreamVersion": "0.7.12",
    // Name of the upstream author.
    "upstreamAuthor": "Alice Bob",
    // URL for the upstream executable or project.
    "upstreamUrl": "https://foo.bar.edu/",
    // Licenses for the upstream tool (e.g., "GPLv3", "MIT").
    "upstreamLicenses": ["GPLv3"],
    // Changelog or release notes; Markdown formatting is supported.
    "whatsNew": "## Changelog\n* Optionally markdown formatted",
    // Custom keys are allowed and preserved by the platform.
    // Use them for internal tracking or additional metadata.
    "myInternalVersion": "v2.3.1",
    "myCustomField": "custom value"
  }
}

`dxapi`

dxapi string (optional) The version of the API that your app uses.

Example:

{
  "dxapi": "1.0.0",
}

`version`

version string Apps only: The version of the app to be built. This version number must be unique from all other versions of the app (published or not).

We recommend following Semantic Versioning conventions for numbering app versions. Semantic Versioning specifies how to change the version number for bug-fix-only updates, backwards-compatible changes, or backwards-incompatible modifications. For publishing workflow details, see App Versioning and Publishing.

Example:

{
  "version": "3.1.41-rc.1",
}

`categories`

You can specify any categories you wish for your app in the "categories" field of the dxapp.json. The following categories are specially recognized by DNAnexus in the UI, supporting organized sections and filtering. Authorized users of your app can use the categories to browse for your app in the Tools Library:

Annotation
Assembly
Debugging
Export
Import
Interactive
Machine Learning
Mappings Manipulation
Read Manipulation
Read Mapping
Reports
RNA-Seq
Statistics
Structural Variation
Translational Informatics
Variation Calling

You can also specify custom category names if none of the recognized categories fit your use case.

Example:

{
  "categories": [
    "Read Mapping"
  ],
}

`inputSpec` and `outputSpec`

The inputSpec and outputSpec fields are JSON arrays that specify app inputs and outputs. These fields are required for apps and strongly recommended for applets.

For complete field specifications, see Input Specification and Output Specification.

When launching from the CLI, comma-separated values are parsed according to the array element class. For example, an array:int input value of 1,2,3 is parsed as [1, 2, 3], while an array:string value of 1,2,3 is parsed as ["1", "2", "3"].

If you omit the inputSpec or outputSpec fields from an applet, the system does not validate the inputs or outputs for that applet. Applets without both input and output specifications cannot be added as stages in workflows.

`runSpec` (Entry Point and Dependencies)

Specifies how to run your app, that is the app's entry point and the interpreter used to evaluate it.

In the following example, the runSpec.file field provides the path to a Python file that contains your application logic.

In this case, the example provides 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 Python applications for examples of the entry point Python function signatures.

Example:

{
  "runSpec": {
    "interpreter": "python3",
    "file": "src/code.py",
    "distribution": "Ubuntu",
    "release": "24.04",
    "version": "0"
  }
}

See I/O and Run Specifications for complete field specifications.

`httpsApp`

httpsApp mapping (optional) Configures the app to run as an HTTPS server accessible via web browser.

Allowed values for ports are 443, 8080, and 8081.

Example:

{
  "httpsApp": {
    "ports": [443, 8080],
    "shared_access": "VIEW"
  }
}

Users with the specified access level to the job's project can access the HTTPS endpoint.

`access` (App Permissions)

By default, apps have limited access to data to ensure user privacy and reproducibility. However, you can request additional permissions for your app when needed.

For project-scoped permissions, project and allProjects accept VIEW, UPLOAD, CONTRIBUTE, or ADMINISTER. The effective permission is always capped by the launching user's own access.

For a complete list of available permission options, see I/O and Run Specifications.

To learn more about different permission types and their implications, see App Permissions.

`ignoreReuse`

ignoreReuse boolean (optional, default: false) When true, disables automatic job reuse. By default, DNAnexus reuses identical jobs (same app, inputs, and instance type) to save time and cost. Set to true if your app has side effects (writes to external services, generates random data) or non-deterministic behavior.

Example:

{
  "ignoreReuse": true
}

`openSource`

openSource boolean (Apps only, optional, default: false) When true, marks the app as open source, making its source code visible to users who have permission to run the app. This helps with transparency and allows users to inspect the code before running it.

Example:

{
  "openSource": true
}

`developers`

developers array of strings (Apps only, optional) List of user IDs (for example ["user-alice", "user-bob"]) who can modify the app. Developers can build new versions, change metadata, and manage the app. By default, only the user who created the app is a developer.

Example:

{
  "developers": ["user-alice", "user-bob"]
}

`authorizedUsers`

authorizedUsers array of strings (Apps only, optional) List of users and organizations that can describe and run the app. Use "PUBLIC" to make the app discoverable to all users.

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 to the app.

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 with a different access list, you need to publish it as a separate app with 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) rebuild the app with authorizedUsers in the dxapp.json file, the access list is overwritten to match the one found in the file.

`regionalOptions`

The regionalOptions field specifies regions where the app can run and region-specific configuration. Each key must be a valid region identifier, such as aws:us-east-1 or azure:westus. If you don't specify this field, the app is enabled only in the region of your project context when the app is built. See Regions for available regions.

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 sufficient to allow apps that don't use certain advanced features to be run in multiple regions.

For apps that use bundled dependencies, use additional resources, or are configured to run on specific instance types, each value of regionalOptions may contain the following keys and values:

systemRequirements - Instance types and cluster specifications per entry point (see I/O and Run Specifications)
bundledDepends - Region-specific bundled dependencies (see bundledDepends)
assetDepends - Region-specific asset dependencies (see assetDepends)
resources - Project ID or array of data object IDs available in that region (see resources)

For applets: Use regionalOptions to specify systemRequirements for the region where the applet is built.

If you specify a key like systemRequirements in regionalOptions, you must do so for all regions and cannot specify it in the top-level runSpec.

Migration from Deprecated Fields

runSpec.systemRequirements and top-level resources are deprecated. The platform and dx build still accept these fields for single-region compatibility. The canonical representation is regionalOptions.<region>, as shown in the After (current) example.

Before (deprecated):

{
  "runSpec": {
    "systemRequirements": {
      "main": {"instanceType": "mem2_ssd1_x4"}
    }
  },
  "resources": "project-xxxx"
}

After (current):

{
  "regionalOptions": {
    "aws:us-east-1": {
      "systemRequirements": {
        "main": {"instanceType": "mem2_ssd1_x4"}
      },
      "resources": "project-xxxx"
    }
  }
}

The deprecated fields work only for single-region apps. Use regionalOptions for all new apps.

Last updated 5 days ago

Was this helpful?

hashtagExamples

hashtagSpecification

hashtagname

hashtagtitle

hashtagsummary

hashtagdescription

hashtagdeveloperNotes

hashtagdetails

hashtagdxapi

hashtagversion

hashtagcategories

hashtaginputSpec and outputSpec

hashtagrunSpec (Entry Point and Dependencies)

hashtaghttpsApp

hashtagaccess (App Permissions)

hashtagignoreReuse

hashtagopenSource

hashtagdevelopers

hashtagauthorizedUsers

hashtagregionalOptions

hashtagMigration from Deprecated Fields

Examples

Specification

`name`

`title`

`summary`

`description`

`developerNotes`

`details`

`dxapi`

`version`

`categories`

`inputSpec` and `outputSpec`

`runSpec` (Entry Point and Dependencies)

`httpsApp`

`access` (App Permissions)

`ignoreReuse`

`openSource`

`developers`

`authorizedUsers`

`regionalOptions`

Migration from Deprecated Fields