ACAT JSON Configuration - Quick Reference

Version: 1.0
Last Updated: February 2026

This quick reference provides essential information for working with ACAT's JSON configuration system.

Configuration File Locations

Configuration Type	Default Location
ActuatorSettings	`%APPDATA%\ACAT\Config\ActuatorSettings.json`
Theme	`%APPDATA%\ACAT\Config\Theme.json`
Abbreviations	`%APPDATA%\ACAT\Config\Abbreviations.json`
Pronunciations	`%APPDATA%\ACAT\Config\Pronunciations.json`
PanelConfig	`%APPDATA%\ACAT\Config\Panels\[PanelName].json`

Note: %APPDATA% typically resolves to C:\Users\[YourName]\AppData\Roaming\

Migration Tool Commands

Convert XML to JSON

ConfigMigrationTool migrate --input "C:\ACAT\Config" --output "C:\ACAT\ConfigJSON" --backup

Preview Migration (Dry Run)

ConfigMigrationTool migrate --input "C:\ACAT\Config" --output "C:\ACAT\ConfigJSON" --dry-run

Validate JSON Files

ConfigMigrationTool validate --input "C:\ACAT\ConfigJSON"

Rollback Migration

ConfigMigrationTool rollback --backup "C:\ACAT\Config"

VS Code IntelliSense Setup

Add to the top of your JSON file:

{
  "$schema": "path/to/schema.json",
  ...
}

Schema Paths

Configuration Type	Schema Path
ActuatorSettings	`../json/actuator-settings.schema.json`
Theme	`../json/theme.schema.json`
PanelConfig	`../json/panel-config.schema.json`
Abbreviations	`../json/abbreviations.schema.json`
Pronunciations	`../json/pronunciations.schema.json`

Common Configuration Patterns

ActuatorSettings - Add Keyboard Switch

{
  "name": "Keyboard",
  "enabled": true,
  "switchSettings": [
    {
      "name": "Trigger",
      "source": "F12",
      "enabled": true,
      "actuate": true,
      "command": "@Trigger",
      "minHoldTime": "@MinActuationHoldTime"
    }
  ]
}

Theme - Define Color Scheme

{
  "name": "Scanner",
  "background": "#232433",
  "foreground": "White",
  "highlightBackground": "#ffaa00",
  "highlightForeground": "#232433"
}

Abbreviations - Add Text Expansion

{
  "word": "btw",
  "replaceWith": "by the way",
  "mode": "Write"
}

Pronunciations - Custom TTS

{
  "word": "github",
  "pronunciation": "git hub"
}

Validation Rules

ActuatorSettings

✅ At least one actuator required
✅ At least one actuator must be enabled
✅ Actuator IDs must be unique GUIDs
✅ Enabled switches that actuate must have a command

Theme

✅ At least one color scheme required
✅ Color scheme names must be unique
✅ Colors must be valid hex codes or color names

Abbreviations

✅ Word and replaceWith cannot be empty
✅ Mode must be "Write", "Speak", or "None"

Pronunciations

✅ Word and pronunciation cannot be empty

Common Commands

Command	Description
`@Trigger`	Primary selection/activation
`@CmdEnterKey`	Simulate Enter key
`@CmdTabKey`	Simulate Tab key
`@CmdUndo`	Undo last action
`@CmdSettings`	Open settings
`@CmdExit`	Exit application

Color Formats

Hex Codes

"background": "#232433"       // RGB
"background": "#FF232433"     // ARGB (with alpha)

Color Names

"background": "White"
"background": "Black"
"background": "Red"
"background": "Blue"

Abbreviation Modes

Mode	Behavior
`Write`	Replace abbreviation with full text in document
`Speak`	Speak full text via TTS without writing
`None`	Disable expansion for this abbreviation

Troubleshooting Quick Fixes

Error: Configuration validation failed

Fix: Check logs for specific errors. Common issues:

Missing required fields
Invalid enum values
Malformed JSON syntax

Error: JSON parsing error

Fix: Validate JSON syntax:

Check for matching brackets {} and []
Ensure all strings have double quotes "
Remove trailing commas at end of arrays/objects

IntelliSense not working

Fix:

Add $schema property to JSON file
Ensure file extension is .json
Reload VS Code window (Ctrl+Shift+P → "Developer: Reload Window")

Changes not taking effect

Fix:

Restart ACAT to reload configuration
Verify correct file location
Check logs for loading errors

JSON Syntax Examples

Valid JSON

{
  "name": "Example",
  "enabled": true,
  "items": [
    { "id": 1, "value": "first" },
    { "id": 2, "value": "second" }
  ]
}

Common Mistakes

// ❌ Bad: Trailing comma
{
  "name": "Example",
  "enabled": true,
}

// ❌ Bad: Single quotes
{ 'name': 'Example' }

// ❌ Bad: Unquoted property names
{ name: "Example" }

// ❌ Bad: Comments (standard JSON)
{
  // This comment is not valid in standard JSON
  "name": "Example"
}
// Note: VS Code JSON parser DOES support comments

Example Files

Copy from schemas/examples/ to get started:

# Windows
copy schemas\examples\abbreviations.example.json %APPDATA%\ACAT\Config\Abbreviations.json

# PowerShell
Copy-Item schemas\examples\abbreviations.example.json $env:APPDATA\ACAT\Config\Abbreviations.json

Schema Files Location

All schemas are in: schemas/json/

actuator-settings.schema.json
theme.schema.json
panel-config.schema.json
abbreviations.schema.json
pronunciations.schema.json

Testing Configuration

Validate with ConfigMigrationTool

ConfigMigrationTool validate --input "C:\ACAT\Config"

Test in VS Code

Open JSON file
Look for red squiggles (validation errors)
Press Ctrl+Space for autocomplete
Hover over properties for documentation

Test in ACAT

Place configuration file in correct location
Restart ACAT
Check logs: %APPDATA%\ACAT\Logs\
Verify behavior in application

Keyboard Shortcuts (VS Code)

Shortcut	Action
`Ctrl+Space`	Show autocomplete suggestions
`Shift+Alt+F`	Format JSON document
`Ctrl+K Ctrl+I`	Show hover information
`F2`	Rename symbol
`Ctrl+Shift+P`	Open command palette

Documentation Links

User Guide: docs/JSON_CONFIGURATION_GUIDE.md
Developer Guide: docs/JSON_CONFIGURATION_DEVELOPER_GUIDE.md
Migration Guide: docs/JSON_CONFIGURATION_MIGRATION.md
Schema README: schemas/README.md
Migration Tool: ConfigMigrationTool README

Support

Check Logs: %APPDATA%\ACAT\Logs\
Example Files: schemas/examples/
Contact: ACAT@intel.com

FilesExpand file tree

JSON_CONFIGURATION_QUICK_REFERENCE.md

Latest commit

History