Reducing Site Property Bloat with JSON

Managing configuration values in OutSystems can quickly lead to a bloated and messy list of Site Properties,one for every feature toggle, API key, timeout value, and more. While functional, this approach becomes increasingly difficult to scale, navigate, and maintain,especially as projects grow and teams expand.

After running into this issue multiple times, I discovered a more efficient approach: storing structured JSON inside a single Site Property. This simple shift offers big benefits: cleaner configuration management, fewer properties to track, easier updates, and better grouping of related values.

Interestingly, there are 58+ community-submitted ideas related to improving Site Property management in OutSystems,ranging from versioning and logging to value grouping and description support. Clearly, this is a pain point many developers face.

---

The Problem with Site Properties Today

Here’s why the default Site Property approach starts to break down at scale:

1. No Organization – There's no native way to sort or group properties, making it hard to find related items.

2. Poor Grouping – Related values (like for a single feature) are scattered, not logically grouped.

3. Hard to Maintain – As more properties get added, understanding their purpose becomes harder.

4. No Logging – There’s no built-in history or change log for Site Property values.

5. Polluted Configuration Space – Single-use keys or temporary values add noise to the list. Too many for simple needs.

---

Why JSON?

Using JSON in a Site Property transforms the way you manage app settings. Here’s why:

Key Benefits

1. Fewer Site Properties – Group multiple values under one JSON property.

2. Logical Grouping – Keep related settings together, e.g., API configs or feature toggles.

3. Dynamic Parsing – Deserialize only what you need, when you need it.

4. Flexible & Scalable – Easily add or remove keys.

5. Simplified Versioning – Manage config as one JSON blob, easier to track changes.

The two most impactful benefits are:

• Having multiple values within a single Site Property

• Allowing additional attributes per config item (like descriptions or types)

---

How to Set Up JSON as a Site Property

Step 1: Create the Site Property

1. Create a new Site Property (e.g., EnvironmentVariables)

2. Set its data type to Text

3. Leave the default value blank (to avoid escaping characters in JSON)

---

Step 2: Define Your JSON Structure

You can define a structure two ways:

• Manually:

  Go to Data > Structures and create a new structure with attributes like Name, Value, and Description.

• From JSON:

  Create your JSON first in an editor, then in Service Studio:

  Right-click Structures > Add Structure from JSON

Example JSON:

[
  {
    "Name": "SiteProp1",
    "Description": "",
    "Value": ""
  },
  {
    "Name": "SiteProp2",
    "Description": "",
    "Value": ""
  }
]

Step 3: Use It in Logic

1. Create a server action (e.g., GetEnvironmentVariables)

2. Use JSONDeserialize to convert the JSON text to a list of structures

3. Return the result for use throughout your app

4. Optionally, expose this through a Service Action if you're in a service module

Tips

• Leave value blank in design time: this avoids escaping issues (like quotes)

• Use strings for booleans in JSON to simplify parsing

• Validate JSON before updating to avoid runtime errors

Going Further: Nested JSON for Advanced Use Cases

You can take this approach even further by using nested JSON. This enables parent-child relationships for more complex configuration scenarios.

Here’s an example from a feature I built called Quick Filtering, where saved search filters are bootstrapped from JSON:

{
  "QuickFilters": [
    {
      "Name": "Todays Report",
      "Group": "Report",
      "Description": "Open Today report",
      "Filters": [
        { "field": "Company", "operator": "equals", "value": "" },
        { "field": "DateFrom", "operator": "greaterThanOrEqual", "value": "Today" },
        { "field": "DateTo", "operator": "greaterThanOrEqual", "value": "Today" },
        { "field": "BankName", "operator": "equals", "value": "" }
      ]
    }
  ]
}

I’ll cover this nested use case in more detail in a follow-up post.

---

Caveats to Consider

Before adopting this approach, here are a few important considerations:

1. Parsing Overhead Every time you read the JSON, you must parse it. This introduces a slight performance cost, especially if done frequently.

2. Manual Editing Risks Updating JSON via Service Center can be error-prone. there’s no validation or syntax highlighting, so a small typo can break parsing.

3. Loss of Type Safety Unlike native Site Properties, JSON values are stored as plain text and require manual type conversion, which can lead to runtime errors if not handled carefully.

4. Character Limit Awareness OutSystems doesn’t show how many characters you're using in the Site Property value. You’ll need to monitor this manually to avoid silent cut-offs or broken JSON.

Summary

Switching to JSON-based Site Properties gives you a powerful way to streamline your configuration logic in OutSystems. It reduces clutter, adds flexibility, and makes your app easier to maintain over time,especially in large or fast-moving projects.

If you find yourself managing dozens of Site Properties with unclear names or single-use purposes, give this approach a try.