Workspace Configuration Format

DataFlex workspaces are configured through .sws files. The current format is JSON (legacy INI-format workspaces can be migrated using df-cli convert).

Full Example

{
  "workspaceName": "MyWorkspace",
  "df": 25.0,
  "description": "My DataFlex application",
  "no-update-html": false,
  "no-html-include-versioning": false,
  "paths": {
    "configFile": "Programs/Config.ws",
    "appHtml": "AppHtml",
    "indexHtml": "AppHtml/index.html",
    "appSrc": ["AppSrc"],
    "data": ["Data"],
    "ddSrc": ["DDSrc"],
    "fileList": "Data/FileList.cfg",
    "connectionIni": "Data/connection.ini",
    "bitmap": ["Bitmaps"],
    "programs": ["Programs"],
    "ideSrc": "idesrc",
    "help": ["Help"]
  },
  "dependencies": [],
  "overrides": {},
  "projects": [],
  "studio": {},
  "package": {}
}

Top-Level Properties

Property	Type	Required	Default	Description
`workspaceName`	string	No	Derived from the `.sws` filename	The display name of the workspace.
`df`	number	Yes	—	The DataFlex version this workspace targets (e.g. `25.0`, `24.1`). Used to select the correct toolchain for compilation and to validate package compatibility.
`description`	string	No	Workspace name	A human-readable description of the workspace. Falls back to the workspace name if not provided.
`no-update-html`	boolean	No	`false`	When `true`, prevents df-cli from automatically updating HTML files during builds or package operations.
`no-html-include-versioning`	boolean	No	`false`	When `true`, disables version query-string suffixes on HTML include references (e.g. `script.js?v=1.2.3`).
`overrides`	object	No	—	Overrides dependency properties. Keys are library IDs, values are version strings or objects with `version`, `sws`, `htmlIncludes`, `cacheCheck`, `type`. Root workspace only; blocks packing.

`paths`

Defines the directory layout of the workspace. All paths are relative to the workspace root directory. Variable substitution (e.g. ${Programs}) is not supported in paths.

Several path properties accept either a single string or an array of strings, allowing the workspace to span multiple directories for a given purpose.

Property	Type	Required	Default	Description
`configFile`	string	No	—	Path to the workspace configuration file (`Config.ws`) used by the DataFlex runtime.
`appHtml`	string	No	—	Root directory for web application HTML files.
`indexHtml`	string \| string[]	No	`<appHtml>/index.html`	Path(s) to the main `index.html` file(s). Supports an array for workspaces that serve multiple HTML entry points (e.g. Flextron applications).
`appSrc`	string \| string[]	No	—	Source code directory or directories. The compiler searches these paths for `.src` and `.pkg` files.
`data`	string \| string[]	No	—	Data file directory or directories containing database files and the file list.
`ddSrc`	string \| string[]	No	—	Data Dictionary source directory or directories.
`fileList`	string	No	—	Path to the `FileList.cfg` file that maps logical filenames to physical database files.
`connectionIni`	string	No	—	Path to the `connection.ini` file used for database connectivity settings.
`bitmap`	string \| string[]	No	—	Directory or directories for bitmap and image resources.
`programs`	string \| string[]	No	—	Output directory or directories for compiled programs and executables.
`ideSrc`	string	No	—	Directory used by the DataFlex Studio IDE for its own source files.
`help`	string \| string[]	No	—	Directory or directories containing help files.

`dependencies`

An array of package dependencies for this workspace. Each entry can be either a string (shorthand for repository packages) or an object (for full control over the source).

String Format

"dependencies": [
  "DAE/my-package",        // repository package: publisher/name
  "../relative/path",      // local workspace path
  "https://git-url.git"   // Git repository
]

The string is parsed to determine the source type automatically: - Strings containing / with no path separators are treated as repository packages (publisher/name). - Strings ending in .git or containing a Git URL are treated as Git dependencies. - Other strings are treated as local workspace paths.

Object Format

For Git dependencies or when specifying version constraints, use the object form:

Property	Type	Required	Description
`source`	string	Yes	The package source. Can be a repository name (`publisher/name`), a Git URL, or a local path.
`version`	string	No	A semantic version constraint (e.g. `^1.0.0`, `~2.1`, `>=1.0.0 <2.0.0`). For Git sources, this is matched against tags.
`sws`	string	No	Subdirectory within the source that contains the `.sws` file. Only relevant for Git dependencies where the workspace file is not in the repository root.

"dependencies": [
  {
    "source": "https://github.com/example/library.git",
    "version": "^2.0.0",
    "sws": "src/workspace"
  }
]

`overrides`

An optional object that overrides dependency properties. Keys identify the library to override and values are either a version string (shorthand) or an object with override properties.

Override Keys

Override keys accept the same notation as dependencies. The key is automatically normalized to the canonical library ID used for lookups, while the original key string is preserved in the JSON on write-back.

Server packages — use Publisher/Name:

"overrides": {
  "DAE/my-lib": "1.2.3"
}

Git libraries — use any URL form you'd use in dependencies:

"overrides": {
  "https://github.com/user/repo.git": "2.0.0",
  "git@github.com:owner/other.git": "1.0.0"
}

All URL forms for the same repository resolve to the same override. For example, https://github.com/user/repo.git and git@github.com:user/repo.git both normalize to github.com/user/repo.git.

If a #version fragment appears in the key (e.g. "DAE/my-lib#1.0.0"), the version is ignored — the override version comes exclusively from the value.

Keys that are not valid dependency strings (e.g. github.com/user/repo.git without a transport prefix) are skipped with a warning.

String Format

A plain version string pins the dependency to that exact version:

"overrides": {
  "DAE/my-lib": "1.2.3"
}

Object Format

An object allows overriding multiple properties:

"overrides": {
  "DAE/my-lib": {
    "version": "1.2.3",
    "sws": "../MyLib/MyLib.sws",
    "htmlIncludes": true,
    "cacheCheck": false,
    "installFiles": false,
    "type": "LOCAL"
  }
}

Property	Type	Description
`version`	string	Pin to an exact version.
`sws`	string	Redirect the library's `.sws` location to a local path. Useful for local development of a package that is normally fetched from a server or Git.
`htmlIncludes`	boolean	Override HTML include generation for this library. When `true`, generates includes even for LOCAL libraries. When `false`, suppresses includes even for non-LOCAL libraries. When omitted, uses default behavior based on library type.
`cacheCheck`	boolean	Override cache integrity verification for this library. When `false`, skips the cache check (hash verification and auto-repair of installed files). File installation itself still occurs. When omitted, uses default behavior.
`installFiles`	boolean	Override file installation for this library. When `false`, skips copying install-pattern files into the root workspace. The dependency's files are still gathered (they appear in the runtime file list) and cache files are still created, but no files are physically copied to the target workspace. HTML include processing is not affected. When omitted, defaults to `true`.
`type`	string	Override the library type. One of `"SRV"`, `"GIT"`, or `"LOCAL"`.

All properties are optional. The override only affects properties that are explicitly set — everything else behaves as the original library would.

Key normalization: Override keys are parsed using the same logic as dependency strings. The following table shows how different key formats are resolved internally:

Override Key	Normalized Library ID
`DAE/my-lib`	`DAE/my-lib` (SRV)
`DAE/my-lib#1.0.0`	`DAE/my-lib` (version ignored)
`https://github.com/user/repo.git`	`github.com/user/repo.git`
`http://github.com/user/repo.git`	`github.com/user/repo.git`
`ssh://git@github.com/user/repo.git`	`github.com/user/repo.git`
`git@github.com:user/repo.git`	`github.com/user/repo.git`
Keys that cannot be parsed as a valid dependency string are skipped with a warning.

Behavior:

Overrides take the highest priority in version resolution — they are checked before the lock file, existing loaded dependencies, and network fetches.
Overrides apply to both direct and transitive dependencies.
Overridden dependencies are not updated or upgraded — the pinned version is always used.
Only the root workspace's overrides take effect. Overrides declared in dependency workspaces are ignored.
A workspace with overrides cannot be packed. Remove all overrides before running df pack.

Local Development Example

To develop a package locally that is normally installed from the server:

"overrides": {
  "DAE/my-lib": {
    "sws": "../MyLib-dev/MyLib.sws",
    "cacheCheck": false
  }
}

This redirects the library to your local working copy. The library retains its original type (SRV) so HTML includes are still generated. Setting cacheCheck to false skips file installation and cache integrity checks since you are actively editing the sources.

When an override sets sws, the overridden workspace is used unconditionally for dependency loading. The overridden workspace's product_version is not validated against the original dependency version constraint. A version-only override still affects version resolution, but once sws is swapped the loaded workspace definition is authoritative.

`projects`

An array defining the build targets in the workspace. Each entry is either a string (the source filename) or an object with additional properties.

String Format

"projects": [
  "MyApp.src",
  "MyUtility.src"
]

Object Format

Property	Type	Required	Description
`name`	string	Yes	The source filename of the project (e.g. `MyApp.src`).
`testProject`	boolean	No	When `true`, marks this project as a test project. Test projects may be treated differently by the Studio or CI tooling. Defaults to `false`.

Any additional properties in the object are preserved as custom metadata and can be read by integrations.

"projects": [
  "MyApp.src",
  {
    "name": "MyTests.src",
    "testProject": true
  }
]

`studio`

Settings for the DataFlex Studio IDE. All properties at the top level of this object (except conditionals and preferredClasses) are primitive values (strings, numbers, or booleans) that map directly to Studio preferences.

Common Studio Properties

Property	Type	Description
`windowsTestProject`	string	The source file used as the default test project in Studio.
`tableEditorReadOnly`	boolean	Whether the table editor opens in read-only mode.
`defaultFormSpacing`	integer	Default spacing (in pixels) between form elements.
`hideSystemClasses`	boolean	Whether to hide system classes in the class browser.

`studio.conditionals`

An object of boolean compiler conditionals. Each key is a conditional name and each value is true or false. These are used as preprocessor conditionals during compilation.

"conditionals": {
  "USE_FEATURE_X": true,
  "LEGACY_MODE": false
}

`studio.preferredClasses`

An object mapping a logical name to a preferred class definition. When Studio creates new objects, it can use these preferred classes instead of the default base classes.

Each entry requires both class and file:

Property	Type	Required	Description
`class`	string	Yes	The DataFlex class name.
`file`	string	Yes	The source file that defines the class.

"preferredClasses": {
  "Button": {
    "class": "cMyButton",
    "file": "cMyButton.pkg"
  },
  "Form": {
    "class": "cMyForm",
    "file": "cMyForm.pkg"
  }
}

`package`

Configuration for publishing this workspace as a distributable package. This section is only needed if you intend to pack, register, or push the workspace to a package repository.

Property	Type	Required	Description
`icon`	string	No	Path to a package icon image file (relative to workspace root).
`license`	string	No	An SPDX license expression (e.g. `"MIT"`, `"MIT OR Apache-2.0"`).
`licenseFile`	string	No	Path to a license text file (relative to workspace root).
`version`	string \| object	No	The package version. Can be a semver string (`"1.2.3"`) or an object (see below).
`install`	array	No	Files to install into consumer workspaces (see below).
`includeFiles`	string[]	No	Glob patterns for files to include when packing (e.g. `"AppSrc/*/"`).
`excludeFiles`	string[]	No	Glob patterns for files to exclude when packing. Evaluated after `includeFiles`.
`htmlIncludes`	array	No	HTML files (scripts, stylesheets) to inject into consumer workspace HTML (see below).

Any additional properties in the package object are preserved as custom metadata.

`package.version`

The version can be specified in two ways:

As a string:

"version": "1.2.3"

As an object:

Property	Type	Required	Description
`major`	integer	Yes	Major version number.
`minor`	integer	Yes	Minor version number.
`revision`	integer	Yes	Revision (patch) number.

"version": {
  "major": 1,
  "minor": 2,
  "revision": 3
}

`package.install`

An array of files that should be copied into workspaces that install this package. Each entry is either a string glob pattern or an object. Patterns support the ${Programs} variable and wildcards (*, ?).

String entry:

"install": [
  "${Programs}/*"
]

Object entry:

Property	Type	Required	Description
`path`	string	Yes	The file path or glob pattern.

"install": [
  "${Programs}/*",
  { "path": "Programs/specific-file.dll" }
]

`package.htmlIncludes`

An array of HTML resources (scripts, stylesheets) that should be injected into the index.html of workspaces that install this package. Each entry is either a string (file path) or an object with additional loading options.

Entries support both local files and CDN URLs (http:// or https://). CDN entries are not included when packing and do not receive version query-string suffixes.

String entry:

"htmlIncludes": [
  "includes/common.html"
]

Object entry:

Property	Type	Required	Default	Description
`file`	string	Yes	—	Path to the HTML include file, or a full CDN URL (e.g. `"https://cdn.example.com/lib.js"`).
`type`	string	No	Inferred from extension	The MIME type hint (e.g. `"mjs"` for ES modules). If omitted, inferred from the file extension.
`async`	boolean	No	`false`	Load the script asynchronously.
`defer`	boolean	No	`false`	Defer script execution until after the document has been parsed. Redundant if `async` is `true` (async implies defer; the `defer` flag is automatically removed in that case).
`integrity`	string	No	—	A Subresource Integrity hash (e.g. `"sha384-..."`). When set and `crossorigin` is not specified, `crossorigin` defaults to `"anonymous"` (required by browsers for SRI checks).
`crossorigin`	string	No	—	The CORS attribute value for the tag (e.g. `"anonymous"`, `"use-credentials"`).
`module`	boolean	No	`false`	When `true`, forces `type="module"` on `.js` script tags (`.mjs` files are always treated as modules regardless of this flag).

"htmlIncludes": [
  "includes/common.html",
  {
    "file": "includes/custom.js",
    "type": "mjs",
    "async": true
  },
  {
    "file": "https://cdn.example.com/bootstrap.css",
    "integrity": "sha384-abc123...",
    "crossorigin": "anonymous"
  },
  {
    "file": "https://cdn.example.com/lib.js",
    "integrity": "sha384-def456...",
    "module": true
  }
]