Appearance

User Configurations Schema Reference ​

Reference for validating per-user configurations stored at %LOCALAPPDATA%\Turbo\Launcher\user-profiles.json.

What You'll Learn

  • How per-user configurations are structured
  • Validating configurations against the JSON schema
  • Usage of the userProfilesVersion field

Purpose ​

This schema validates the structure of the per-user configurations file. It does not validate values against enterprise constraints (regex/path allowlists) or cross-reference templateRef to enterprise templates — those validations are enforced by the Launcher at runtime.

Schema file

Top-level structure ​

json
{
  "userProfilesVersion": 1,
  "profiles": [ ... ]
}

Fields ​

  • userProfilesVersion (integer) — Version of the user configurations file format.
  • profiles (array<UserProfile>) — User-defined configurations based on enterprise templates.

Versioning and compatibility ​

The userProfilesVersion field versions the per-user configuration file format independently of the enterprise Launcher policy schema.

Client behavior:

  • If userProfilesVersion is equal to the client’s supported version:
    • The file is validated against launcher-user-configurations.schema.json and loaded normally.
  • If userProfilesVersion is lower than the supported version:
    • The file is treated as backward-compatible.
    • Unknown fields are ignored; defaults apply where newer fields are missing.
  • If userProfilesVersion is greater than the supported version:
    • The client treats the configuration file as unsupported.
    • The file is ignored and the user falls back to built-in defaults or previously known-good configurations.
    • An audit or telemetry event should record the mismatch for troubleshooting.

userProfilesVersion does not affect policyVersion or the Launcher policy schema version.

UserProfile ​

json
{
  "id": "user-project-alpha",
  "displayName": "Project Alpha Configuration",
  "templateRef": "p4-shared-environment",
  "configuration": {
    "environmentVariables": {
      "P4PORT": "ssl:p4.alpha.trusted.com:1666",
      "P4USER": "jdoe",
      "P4CLIENT": "jdoe_ws_alpha"
    },
    "mounts": [
      {
        "name": "RepoA",
        "ruleRef": "src-ro",
        "source": "D:\\Repos\\RepoA",
        "destination": "P:\\src\\RepoA",
        "options": ["read-only"]
      }
    ]
  }
}

Fields ​

FieldTypeRequiredDescription
idstringYesStable identifier; unique within this file (kebab-case recommended).
displayNamestringYesUI label for the configuration.
templateRefstringYesReferences configurationTemplates[].id from the active enterprise policy (validated at runtime).
configurationProfileConfigurationYesValues that must satisfy enterprise template constraints.

ProfileConfiguration ​

json
{
  "environmentVariables": { "KEY": "value" },
  "mounts": [
    {
      "name": "optional",
      "ruleRef": "template-rule-id",
      "source": "D:\\Repos\\RepoA",
      "destination": "P:\\src\\RepoA",
      "options": ["read-only"],
      "os": ["windows"]
    }
  ]
}

Fields ​

FieldTypeRequiredDescription
environmentVariablesobject<string,string>Yes*Key/value pairs. Keys must be allowed by the referenced template; required keys must be present; values must match any validationPattern (runtime validation).
mountsarray<UserMount>Yes*User-declared mounts validated against template mount rules (allowedSourcePatterns, allowedDestinationPatterns, allowedOptions). At least one of environmentVariables or mounts must be present.

UserMount ​

FieldTypeRequiredDescription
namestringNoOptional identity key used for merge/tie-breaks.
sourcestringYesHost path; supports well-known tokens and Windows env vars.
destinationstringYesContainer path inside the runtime.
options("read-write" | "read-only")[]NoMount access options.
ruleRefstringNoOptional reference to template mounts.rules[].id for audit.
os("windows"|"macos"|"linux")[]NoOptional OS constraint for the mount.

Using the JSON Schema ​

Add $schema to enable editor IntelliSense and basic structure validation.

Minimal file header

json
{
  "$schema": "https://schemas.turbo.net/launcher-user-configurations.schema.json",
  "userProfilesVersion": 1,
  "profiles": []
}

Local (when editing inside this repo)

json
{
  "$schema": "./reference/user-configurations-schema.json",
  "userProfilesVersion": 1,
  "profiles": []
}

Validate with AJV ​

Install AJV (if not already):

bash
npm i -g ajv-formats ajv-cli

Validate a user-profiles.json file:

bash
npx ajv validate \
  -s docs/src/policy/reference/user-configurations-schema.json \
  -d "%LOCALAPPDATA%/Turbo/Launcher/user-profiles.json"

Notes

  • JSON Schema validation ensures structure only. Runtime enforces:
    • templateRef exists in enterprise configurationTemplates.
    • Env var keys/required/regex constraints defined by the template.

Turbo.net © 2025