# 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`](https://documentation.dnanexus.com/api/running-analyses/applets-and-entry-points#api-method-applet-new) and [`/app/new`](https://documentation.dnanexus.com/api/running-analyses/apps#api-method-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)

{% hint style="info" %}
**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](#migration-from-deprecated-fields).
{% endhint %}

{% tabs %}
{% tab title="Comprehensive" %}
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](#specification) section below for root-level field documentation and [I/O and Run Specifications](https://documentation.dnanexus.com/developer/api/running-analyses/io-and-run-specifications) for complete API reference.

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

{% code title="dxapp.json" overflow="wrap" %}

```jsonc
{
  // 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": "alice@example.edu"
  },
  // 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"}
      ]
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Basic" %}
This example shows commonly used fields for a typical analysis app with reasonable production practices.

**Use this for:** Most production apps with moderate complexity.

{% code title="dxapp.json" overflow="wrap" %}

```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": "alice@example.edu",
    "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"}
      }
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Minimal" %}
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.

{% code title="dxapp.json" overflow="wrap" %}

```jsonc
{
  "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"
  }
}
```

{% endcode %}

For apps, add these required fields:

{% code title="dxapp.json" overflow="wrap" %}

```jsonc
{
  "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"
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

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`](https://documentation.dnanexus.com/api/running-analyses/applets-and-entry-points#api-method-applet-new), [`/app/new`](https://documentation.dnanexus.com/api/running-analyses/apps#api-method-app-new), and the [I/O and Run Specifications](https://documentation.dnanexus.com/developer/api/running-analyses/io-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](https://documentation.dnanexus.com/api/running-analyses/apps#app-versioning-and-publishing) into an app, then its ID is of the form `app-[name]/[version]`. An app's name cannot be changed across versions.

Example:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```jsonc
{
  // Arbitrary metadata for your app or applet.
  "details": {
    // Contact email for the app/applet author or maintainer.
    "contactEmail": "alice@foo.edu",
    // 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:

```json
{
  "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](https://semver.org) 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](https://documentation.dnanexus.com/api/running-analyses/apps#app-versioning-and-publishing).

Example:

```json
{
  "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:

```json
{
  "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](https://documentation.dnanexus.com/api/running-analyses/io-and-run-specifications#input-specification) and [Output Specification](https://documentation.dnanexus.com/api/running-analyses/io-and-run-specifications#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](https://documentation.dnanexus.com/developer/api/running-analyses/workflows-and-analyses).

### `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](https://documentation.dnanexus.com/developer/apps/execution-environment), handling possible errors, and saving your app's output. See the [example Python applications](https://documentation.dnanexus.com/getting-started/developer-tutorials/python) for examples of the entry point Python function signatures.

Example:

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

See [I/O and Run Specifications](https://documentation.dnanexus.com/api/running-analyses/io-and-run-specifications#run-specification) 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:

```json
{
  "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](https://documentation.dnanexus.com/api/running-analyses/io-and-run-specifications#access-requirements).

To learn more about different permission types and their implications, see [App Permissions](https://documentation.dnanexus.com/developer/apps/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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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) rebuilds 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](https://documentation.dnanexus.com/developer/api/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](https://documentation.dnanexus.com/developer/api/running-analyses/io-and-run-specifications), 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](https://documentation.dnanexus.com/api/running-analyses/io-and-run-specifications#run-specification))
* `bundledDepends` - Region-specific bundled dependencies (see [`bundledDepends`](https://documentation.dnanexus.com/api/running-analyses/io-and-run-specifications#run-specification))
* `assetDepends` - Region-specific asset dependencies (see [`assetDepends`](https://documentation.dnanexus.com/api/running-analyses/io-and-run-specifications#run-specification))
* `resources` - Project ID or array of data object IDs available in that region (see [`resources`](https://documentation.dnanexus.com/api/running-analyses/apps#api-method-app-new))

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

{% hint style="warning" %}
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`](#runspec-entry-point-and-dependencies).
{% endhint %}

#### 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):**

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

**After (current):**

```json
{
  "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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.dnanexus.com/developer/apps/app-metadata.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.