Understanding APEXlang Deployment Files

Use an APEXlang JSON deployment file to configure important deployment-related values related to application, workspace, subscription, and theme. This separates deployment details from the core app definition .apx files.

The deployment file is environment-specific. You can define multiple sets of deployment configuration values, each in its own deployment JSON file with a meaningful name. For example, you might name the files test-env.json and prod-env.json for deployment to TEST and PROD environments. The ./deployments/default.json file contains the default settings. If you create additional files, put them in this same ./deployments subdirectory.

When importing with SQLcl and when a non-default configuration is required, specify a deployment file using the -deployment <path-to-deployment-file> option.

Default File Contents

When you create a new Oracle APEX application and export it in APEXlang format, the ./deployments/defaults.json file contains only the minimum required settings, containing the application id and the checksum salt (which is used to generated bookmarked URLs).

{
  "app" : {
    "id" : 1020
  }
  "sessionStateProtection" : {
    "checksumSalt" : "727D6A4B60F8B5E1F67F84EA68BE525ADD2142F04480335BBCB22E886B98ED74"
  }
}

Example of All Supported Deployment File Properties

The following example shows every supported APEXlang deployment file option that can influence deployment handling. Most properties are optional. Where applicable, values contained in the deployment file override ones the application definition might provide (for example, workspace name, application name, and alias).

{
  "app": {
    "id": 1020,
    "name": "Customer Portal",
    "alias": "customer-portal",
    "databaseSession": {
      "parsingSchema": "CUST_PORTAL_APP"
    },
    "sessionStateProtection": {
      "allowUrlsCreatedAfter": "2026-05-12T20:50:24",
      "checksumSalt": "0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF"
    },
    "runtime": {
      "logging": true,
      "debugging": false
    },
    "proxy": {
      "proxyServer": "proxy.example.com:8080",
      "noProxyDomains": "localhost,internal.example.com"
    },
    "staticFiles": {
      "appFilesPath": "/apps/customer-portal/files/",
      "apexFilesPath": "/i/"
    },
    "availability": {
      "buildStatus": "runAndBuild"
    }
  },
  "workspace": {
    "name": "CUSTOMER_PORTAL"
  },
  "subscription": {
    "masterApps": {
      "100": 105,
      "200": 205
    }
  },
  "theme": {
    "advanced": {
      "filePrefix": "i"
    }
  }
}

The example values are placeholders. Replace them with values appropriate for the target environment.

Caution: Do not copy the example checksum salt above into your application deployment file.

Supported Properties

The table belows lists all supported properties. The category column describes the containing JSON object.

The values in application.apx and other application source files are the normal source values. Add a property to the deployment file when you need to override that value for a deployment. Not every supported property needs to appear in every generated or user-created default.json; when a property is absent, its source value or target-environment default is used.

Category	Property	Type	Default or Fallback	Description
Application	`app.id`	integer	Application ID from export	Target APEX application ID. APEX export writes this value directly.
Application	`app.name`	string	Include only to override `application.apx` value	Application display name.
Application	`app.alias`	string	Include only to override `application.apx` value	Application alias. The alias must satisfy the normal APEX uniqueness rules.
Database session	`app.databaseSession.parsingSchema`	string	Application owner or target-environment default	Schema used to parse and execute the application’s SQL and PL/SQL. When exporting from a workspace with only one assigned schema, APEX omits this property unless you supply an owner override on export.
Session state protection	`app.sessionStateProtection.allowUrlsCreatedAfter`	string	Omitted when checksumSalt has not been modified.	Date and time after which bookmarked URLs containing checksums remain usable. Use the database timestamp format `YYYY-MM-DD"T"HH24:MI:SS`; the value has no timezone component. Older bookmarked URLs fail checksum validation when the application session state protection rules require a checksum.
Session state protection	`app.sessionStateProtection.checksumSalt`	string	Auto generated. If using auto generated value, export the application to store the value into the default.json file.	Used to generate and validate checksums in bookmarked URLs. To generate a custom checksum salt, generate 32 cryptographically secure random bytes and encode them as hexadecimal. The result must contain exactly 64 hexadecimal characters (0–9, A–F). Do not derive the salt from the application ID, name, password, or other predictable value. Changing this value invalidates URLs containing checksums generated with the previous salt.
Runtime	`app.runtime.logging`	boolean	`true`	Enables application activity/page-view logging. The effective value can also be restricted by the instance activity-logging configuration.
Runtime	`app.runtime.debugging`	boolean	`false`	Controls whether debug mode can be enabled from a browser at runtime. Programmatic debug activation and development-environment rules can still apply.
Proxy	`app.proxy.proxyServer`	string	No application-level proxy	Proxy server used for outbound requests made in the application. An instance-level proxy configuration can also affect outbound requests.
Proxy	`app.proxy.noProxyDomains`	string	No bypass list	Comma-delimited hosts and domains that bypass the application proxy. This setting is meaningful when `proxyServer` is configured.
Static files	`app.staticFiles.appFilesPath`	string	Application files stored with the application in the database	Virtual path or URL used for application static files referenced by `#APP_FILES#`. Leave it empty or omit it to use files stored with the application definition.
Static files	`app.staticFiles.apexFilesPath`	string	APEX installation image prefix, commonly `/i/`	Virtual path or URL used for shared APEX static resources referenced by `#APEX_FILES#`.
Availability	`app.availability.buildStatus`	string	`runAndBuild`	Controls whether the imported application can be developed as well as run. Allowed values are `runAndBuild` and `runOnly`; `runOnly` is intended for a runtime-only deployment.
Workspace	`workspace.name`	string	Connection or session workspace	Target APEX workspace name. This is useful when the current schema is linked with multiple workspaces.
Subscription	`subscription.masterApps`	object	Omitted when no subscribed master applications exist	Maps the application IDs of subscription sources in the exported application to the application IDs of replacement subscription sources in the target workspace. The property name is the source application ID represented as a JSON object key string; the value is the destination application ID as a number. For example, `"100": 105` means that subscriptions originally pointing to application 100 should resolve to application 105 during import, and `"200": 205` remaps application 200 to 205. The destination applications must exist in the target workspace. When no remapping is needed, the exporter writes the same ID on both sides.
Theme	`theme.advanced.filePrefix`	string	Theme definition value; include `theme.advanced.filePrefix` only to override it	Virtual path or URL used for theme files. The value can also use `#APEX_FILES#` when the theme files are hosted with shared APEX static resources. This property is not normally included in a generated `default.json`; add it when you need to override the theme definition value for a deployment.

Value Precedence

The deployment file selection rules determine which file supplies deployment values. SQLcl uses an explicitly selected deployment file or, when no file is selected, deployments/default.json from the input directory or ZIP. For each configurable property, the effective value is resolved in this order:

An explicit SQLcl import option or compiler override, when applicable (for example, -schema).
A value already set through an APEX_APPLICATION_INSTALL.SET_* API, when supported. SQLcl options that are implemented through these APIs are included at this level. For subscription mappings, an explicitly set API mapping is not overwritten by a deployment-file mapping.
A value from the selected deployment file. If no file was explicitly selected, this is the value from deployments/default.json in the input directory or ZIP.
The value in an .apx source file, most commonly application.apx, or the target-environment default.

Application ID and workspace selection have additional fallback behaviour. If the current schema uniquely identifies a workspace, APEX infers it. In addition, APEX automatically generates an application id when not provided.