JSON Configuration Migration Guide

Overview

ACAT has migrated from XML to JSON for configuration files. This guide explains the changes and how to migrate existing configurations.

Migrated Configuration Types

✅ Abbreviations Configuration

• Old Format: Abbreviations.xml
• New Format: Abbreviations.json
• POCO: AbbreviationsJson (namespace: ACAT.Core.Configuration)
• Validator: AbbreviationsValidator (namespace: ACAT.Core.Validation)

JSON Structure

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

Valid Mode Values

• Write - Expand abbreviation as text
• Speak - Speak the expansion
• None - No expansion

Example

See /schemas/examples/abbreviations.example.json for a complete example.

✅ Pronunciations Configuration

• Old Format: Pronunciations.xml
• New Format: Pronunciations.json
• POCO: PronunciationsJson (namespace: ACAT.Core.Configuration)
• Validator: PronunciationsValidator (namespace: ACAT.Core.Validation)

JSON Structure

{
  "pronunciations": [
    {
      "word": "github",
      "pronunciation": "git hub"
    }
  ]
}

Example

See /schemas/examples/pronunciations.example.json for a complete example.

✅ Previously Migrated (from Ticket #7)

• Actuator Settings: ActuatorSettings.json
• Panel Configuration: PanelConfig.json
• Theme Configuration: Theme.json

Backward Compatibility

All migrated configuration classes maintain backward compatibility with XML files:

1. File Detection: The system checks for JSON files first, then falls back to XML if JSON is not found
2. Automatic Format Detection: Based on file extension (.json or .xml)
3. Transparent Loading: No code changes required in consuming code

Example File Lookup Order

For Abbreviations:

1. Looks for Abbreviations.json in resources directory
2. Looks for Abbreviations.json in user directory
3. Falls back to Abbreviations.xml in resources directory
4. Falls back to Abbreviations.xml in user directory
5. Creates default Abbreviations.json if none found

Migration Steps

Manual Migration

1. Locate your existing XML configuration file
2. Convert to JSON format using the examples as a template
3. Save with .json extension
4. The system will automatically use the JSON file

Using ConfigMigrationTool

The ConfigMigrationTool application can convert XML configurations to JSON automatically.

Features

Validation

All JSON configurations are validated using FluentValidation:

• Required fields are checked
• Data types are validated
• Enum values are verified
• Custom business rules are applied

Error Handling

• Invalid JSON: Falls back to defaults with error message
• Missing File: Creates default configuration
• Validation Failure: Falls back to defaults with detailed error messages

JSON Format Features

• Comments: Supports // and /* */ style comments
• Trailing Commas: Allows trailing commas for easier editing
• Case-Insensitive: Property names are case-insensitive during deserialization
• Indented Output: Saved files are pretty-printed for readability

Code Examples

Loading Abbreviations

var abbreviations = new Abbreviations();
abbreviations.Load(); // Automatically tries JSON first, then XML

// Or specify a file
abbreviations.Load("/path/to/Abbreviations.json");

Saving Abbreviations

var abbreviations = new Abbreviations();
abbreviations.Add(new Abbreviation("btw", "by the way", AbbreviationMode.Write));
abbreviations.Save(); // Saves as JSON

Using JsonConfigurationLoader Directly

var loader = new JsonConfigurationLoader<AbbreviationsJson>(
    new AbbreviationsValidator(),
    logger
);

var config = loader.Load("/path/to/Abbreviations.json");

Testing

Comprehensive test coverage is provided in:

• ACATCore.Tests.Configuration/AbbreviationsTests.cs
• ACATCore.Tests.Configuration/PronunciationsTests.cs

Run tests with:

cd src/Libraries/ACATCore.Tests.Configuration
dotnet test

TTS Engine Settings

TTS engine pronunciation file references have been updated:

• SAPI Engine: SAPIPronunciations.json (was .xml)
• TTS Client: TTSPronunciations.json (was .xml)

Legacy XML files will still work due to backward compatibility.

Troubleshooting

"Configuration validation failed"

Check the application logs for specific validation errors. Common issues:

• Empty required fields
• Invalid enum values (e.g., mode must be "Write", "Speak", or "None")
• Malformed JSON syntax

"Configuration file not found"

The system will create a default configuration. Check:

1. File path is correct
2. File has read permissions
3. File extension is .json or .xml

"JSON parsing error"

Check JSON syntax:

• All brackets and braces are matched
• Strings are properly quoted
• No trailing commas at the end of arrays/objects (unless using comment-tolerant parser)

Future Migrations

Other configuration types may be migrated to JSON in future releases. The pattern established here will be followed:

1. Create JSON POCO
2. Create FluentValidation validator
3. Update loader to support both JSON and XML
4. Add comprehensive tests
5. Update documentation

Related Files

• POCOs: /src/Libraries/ACATCore/Configuration/
• Validators: /src/Libraries/ACATCore/Validation/
• Tests: /src/Libraries/ACATCore.Tests.Configuration/
• Examples: /schemas/examples/
• JsonConfigurationLoader: /src/Libraries/ACATCore/Utility/JsonConfigurationLoader.cs