# App configuration (XML/JSON)

> Reference for the configuration behind an app: the XML structure and schema version, what saving preserves, the JSON representation and schema exposed through MCP, and an element reference.

Everything configured in the app editor is stored as one configuration document per app. It is stored as XML and exposed as typed JSON through the MCP server. This page is a reference for people and agents who read or write that configuration directly. For what the settings mean, follow the links to the conceptual pages: [Datasets](datasets.html), [Workspaces and components](components.html) and [Actions](actions.html).

## Ways to access the configuration

| Route | Read | Write | Format |
|---|---|---|---|
| App editor | yes | yes | graphical |
| *Edit XML* (*Redigera XML*) in the app menu (⋯) | yes | yes | XML |
| MCP: `load_complete_app_config`, `search_app_config` | yes (v1 and v2 plans) | | JSON |
| MCP: `patch_app_config`, `overwrite_complete_app_config`, `create_app_with_config` | | yes (**v2 plans only**) | JSON |

The admin editor reads and writes the XML through these endpoints:

| Operation | Endpoint |
|---|---|
| Read | `GET /api/admin/plans/{planId}/apps/{appId}/xml` |
| Save | `POST /api/admin/plans/{planId}/apps/{appId}/xml` |
| Validate | `POST /api/admin/appconfig/validate/xml` and `…/xml/configvalidated` |

!!! warning "Internal endpoints"
    The admin endpoints above belong to the internal API used by the editor. They are not part of the public, supported REST API and may change without notice. To read and write app configuration programmatically, use the [MCP server](ai-agents.html) (see [JSON representation via MCP](#json-representation-via-mcp)).

## Before editing by hand

### Saving is not round-trip

When a configuration is saved, the server does not store the submitted XML as it is. It parses it into the configuration model, serialises the model to new XML, and then patches the new XML with selected parts of the old one. That patch list contains exactly one path today:

```
/App/Config/Datasets/DataSet/Styles
```

(`Styles` is a legacy dataset styling block with no editor. The model only reports that it exists.)

Consequences:

- Anything the model does not read is **dropped on the next save**: XML comments, custom or unknown attributes, formatting and element order that the model does not preserve.
- Attributes that are only read by the legacy app engine, such as `AllowPartialUserFlow` and `AggregationExpression`, and the old `Konstrukt_Std_*` component types, are not read by the current model and do not survive.
- A hand edit is kept only if it is expressed in elements and attributes that the model reads. Check the result by reading the configuration back after saving.

### Component errors are found late

The XML validation schema is deliberately open around `<Component>`, because it cannot vary the allowed content by the `Type` attribute. An error inside a component is therefore only found when the configuration is deserialised, and the message has no line or column number. Change one component at a time.

### What is not in the configuration

The app's **name**, **description**, status and some access flags are stored on the app record, not in the configuration. The `Name` and `Description` attributes on `<App>` that appear in the XML validation schema are not read. They would only be stale copies.

In practice:

- copying the XML from one app to another does not copy the name or description;
- through MCP, name and description are parameters of `create_app_with_config`, not part of the JSON.

### Schema version and migrations

The root element carries `SchemaVersion`. The current version is **1.50**. When a configuration is read it is migrated step by step (`1.39 → 1.42 → 1.45 → 1.452 → 1.48 → 1.50`), followed by migrations that depend on the plan version. These migrations convert dataset expressions and remove legacy action components in v2 plans. Always write the current version.

## XML structure

```xml
<App SchemaVersion="1.50">
  <Config>
    <Datasets>
      <DataSet Id="1" Name="Budget">                   <!-- 1..n -->
        <Groupings><Initial><Grouping … /></Initial></Groupings>
        <ValueTypes SortById="false" SortingMethod="Natural">
          <ValueType Value="Amount" Aggregation="Sum" SpreadValue="0" Condition="…">
            <ExcludedDimensionValueDefaults>
              <Code DimensionId="Project" Value="0" />
            </ExcludedDimensionValueDefaults>
          </ValueType>
        </ValueTypes>
        <InitialValues Enabled="true"><Set …>…</Set></InitialValues>
        <LockedValues Enabled="true"><Set>…</Set></LockedValues>
        <Filters><Filter>…</Filter></Filters>
        <Expressions><Dimensions DimensionId="…"><Expression … /></Dimensions></Expressions>
        <DataTypes … />
        <InheritRowLevelAccess EnableDimensionBasedAccess="true" ReadOnly="false" />
      </DataSet>
    </Datasets>
  </Config>
  <Workspaces>
    <Workspace Id="1" Name="Budget entry" Hidden="false">   <!-- 1..n -->
      <Filter>…</Filter>
      <ActionComponents>…</ActionComponents>
      <Layout Type="MultiPage|Matrix">…</Layout>
      <PlanData Value="Selected" UsePlanName="false" />
      <References><Reference Id="12" Selected="true" /></References>
      <DataTypeSortOrder>…</DataTypeSortOrder>
      <ValueTypes>…</ValueTypes>
      <ValueTypeSortOrder>…</ValueTypeSortOrder>
    </Workspace>
  </Workspaces>
  <Access Locked="false" Enabled="true" AccessListId="3" />
</App>
```

`Access` holds app access (see [Apps](apps.html#app-access)). Without it, default access applies.

### Recurring idiom: absence, presence, presence with a flag

Several three-state settings in the editor are encoded by whether an element exists and whether it carries a flag:

| Setting | Absent | Present | Present with flag |
|---|---|---|---|
| Workspace filter | Unavailable | Available | Required (`IsRequired="true"`) |
| Workspace reference | Unavailable | Available (`Selected="false"`) | Default (`Selected="true"`) |

### Dimension and property rows

A dataset dimension and a dataset property are both `<Grouping>` elements:

```xml
<!-- a dimension -->
<Grouping Value="Department" SortByDimValueNo="false" SortingMethod="Natural" />

<!-- a property of a dimension -->
<Grouping Value="DimTagNo" DimTagGroupId="101" DimensionId="Account"
          SortByDimValueNo="false" SortingMethod="Natural" DisplayFormatId="4" />
```

`Value="DimTagNo"` marks the row as a property. The property is identified by `DimTagGroupId` together with `DimensionId`.

### Initial values sources

The expansion source is not written explicitly. It is derived:

| XML | Source |
|---|---|
| `TakeFromDataSet="true"` | `ValuesInDataset` |
| `<Values>` present | `SpecifiedValues` |
| no `<Values>` | `AllValuesInDimension` |

Further rules:

- `DimensionId="ValueTypeId"` is the virtual dimension used to select value types.
- `<References><Ids>` expands from a reference; only the first `<References>` element is used.
- `<PlanDataValueTypes><Ids>` expands from other value types.
- `ExpandAllValueTypes` defaults to `true` when no value types are listed, otherwise `false`.
- `Enabled="false"` on `<InitialValues>` or `<LockedValues>` makes the whole block ignored.
- `DimensionId="DataType"` is ignored in both blocks. An empty `<Set />` is harmless.

### Expressions

- `<Dimensions DimensionId>` says which dimension the expression creates a value on.
- `DimValueNo` is the code and `DimValueName` the display name. An empty name is read as a single space, which is how blank spacer rows are made.
- `Language` is `Kex` (v2 plans) or `JavaScript` (v1). A missing attribute means `JavaScript`. On save, the language is set from the plan version.
- `Numerator` + `Denominator` (with an empty `Value`) marks a `LegacyQuot` expression. Otherwise `Value` holds a `Standard` expression.
- Writeback attributes: `WritebackExpression`, `WritebackDimValueNo`, `WritebackSpread`, `EditPrecision`. Older files without `WritebackSpread` on value-type-dimension expressions are backfilled to `Proportional`.

### Column setting IDs

`<Setting Type="Column">` identifies the column with `Value`, while `<Setting Type="ColumnGroup">` uses `Id`. The attribute names differ and are easy to mix up. (In JSON both use `Id`.) Column IDs follow the grammar `<axis>[~<code>]`:

| Pattern | Example | Column |
|---|---|---|
| `GROUP_COL_ID` | | the merged grouping column |
| `<DimensionId>` | `Department` | the dimension's column (or its total column when pivoted) |
| `<DimensionId>~<code>` | `Month~202601` | a pivoted column for one dimension value |
| `<DimensionId>_<propertyId>` | `Account_101` | a property column |
| `<DimensionId>_<propertyId>~<code>` | `Month_102~01` | a pivoted property column |
| `ValueTypeId~<code>` | `ValueTypeId~Amount` | a pivoted value type column |

See [Workspaces and components](components.html#column-settings) for what the settings do.

### Scripts in attributes

An action's script is stored in the `Script` attribute, so that whitespace and line breaks are preserved. Escape `"`, `<`, `>` and `&` as XML entities when editing by hand.

## XML and JSON names

The JSON model uses different names for some XML attributes:

| XML | JSON | GUI |
|---|---|---|
| `Grouping` rows | `DatasetDimensions[]` | dimensions matrix |
| `DimTagGroupId` | `DimensionPropertyId` | property |
| `SortByDimValueNo="true"` / `"false"` | `SortBy: "Code"` / `"Name"` | Sort by |
| `DisplayFormatId` | `DisplayFormatId` | Display as |
| `IncludeDimValueNo` (legacy) | `DisplayFormatOverride` | not supported in the current end-user interface |
| `ValueType/@Name` | `NameOverride` | name override |
| `SpreadValue` | `SpreadOverride` | Spread |
| `DimValueNo` / `DimValueName` | `DatasetDimensionValueCode` / `DatasetDimensionValueName` | Code / Name |
| `WritebackDimValueNo` | `WritebackExpression.DatasetDimensionValueCode` | destination |
| `MultiSelect` | `Multiple` | Multiple |
| `SortById` | `SortBy` | |
| `Layout/@Type` | `Layout.$type` (`MultiPage`, `Matrix`) | Layout |
| `Component/@Type` | `$type` | Type |
| `<Variables>` | `VariableInputs` | Variables |

Enumerations are stored by name except where a numeric code is shown in the tables on the conceptual pages (spread, format code, line state, line access, display format).

## JSON representation via MCP

The MCP server exposes the configuration as JSON:

| Tool | Purpose |
|---|---|
| `get_app_config_schema` | describe the configuration types: without `types` the root and every type name; with `types` (`["WorkspacePage", "MatrixLayout"]`) each type's properties, which are required, the `$type` of each variant and the types they refer to |
| `search_app_config` | find parts of a configuration with a JSONPath (`$..MainComponent`) or JSON Pointer; each match returns its pointer |
| `load_complete_app_config` | read a whole configuration (v1 and v2 plans) |
| `patch_app_config` | change parts of a configuration with a JSON Patch (**v2 plans only**) |
| `overwrite_complete_app_config` | replace a whole configuration (**v2 plans only**) |
| `validate_complete_app_config` | validate a configuration without saving (v1 and v2 plans) |
| `create_app_with_config` | create an app with name, description and configuration in one call (**v2 plans only**) |
| `delete_app` | permanently delete an app |
| `list_apps` | list apps in a plan (`id` is a GUID, plus `name` and `description`) |

Reads return the configuration together with an **etag**. Pass it as `ifMatch` to `patch_app_config` or `overwrite_complete_app_config`, and the write is rejected if someone changed the configuration in the meantime.

`patch_app_config` takes an RFC 6902 JSON Patch array (`add`, `remove`, `replace`, `move`, `copy`, `test`) plus `merge`, which applies a JSON Merge Patch at a position and leaves unnamed properties alone. Positions are JSON Pointers from `search_app_config`, or a JSONPath that matches exactly one position. The whole patch is applied together: if one edit fails, nothing is saved. `dryRun: true` validates and reports the changes without saving.

```json
[{"op": "test",  "path": "/Workspaces/0/Name", "value": "Budget entry"},
 {"op": "merge", "path": "/Workspaces/0", "value": {"Name": "Budget input"}}]
```

Prefer `search_app_config` and `patch_app_config` to reading and rewriting the whole configuration; configurations can be large. Use `replace`, not `merge`, when changing the `$type` of a node, so that properties of the old type do not survive.

The JSON is described by a JSON Schema (draft 2020-12) with 153 definitions. Its root is `AppConfigModel` with the required members `Id`, `PlanId`, `Datasets`, `Workspaces` and `Access`. Read the types you need with **`get_app_config_schema`**: the full schema is about 123,000 characters, too large for most agents to use. It is also published as the MCP resource `konstrukt://schema/app-config`, for clients that can attach resources.

When a configuration does not match the format, `validate_complete_app_config`, `patch_app_config`, `overwrite_complete_app_config` and `create_app_with_config` show the expected shape of the type in the error: its properties, which are required, and the valid `$type` values.

Points to know:

- **Polymorphism uses `$type`** (layouts, components, grid axes, settings, filters, expressions, row-level access, action components, variables). Component filter items and presentation-rule value conditions use **`Type`** instead.
- Several fields are polymorphic (chart axes, action targets). Guessing their shape can produce a configuration that parses but silently omits data.
- The model may contain implementation-specific details, and its structure is not guaranteed to be stable across versions. Always read the schema from the server rather than relying on a copy.
- **Colours** are serialised without a leading `#` (`"Light": "1F9AAD"`), although the schema text describes them as hex with `#`. Follow what `load_complete_app_config` returns.
- Output can contain `LegacyActionComponents: []` on workspaces, which the schema does not define.
- **Dataset IDs are integers** (`"Id": 1` on a dataset, `"DatasetId": 1` on a component). Component IDs are strings. Earlier versions of the format used strings for dataset IDs as well; a string now fails with *The JSON value could not be converted to System.Int32*.
- The root `Id` (the app's GUID) is required, also when creating an app.
- Reads return empty collections explicitly (`"Expressions": []`, `"ColumnSettings": []` …).
- MCP has no tool for renaming an app, changing its description or copying it.

A minimal configuration, for orientation only (validate against the schema before use):

```json
{
  "Id": "…", "PlanId": 30,
  "Datasets": [{
    "Id": 1, "Name": "Budget",
    "DatasetDimensions": [
      {"DimensionId": "Account", "SortBy": "Code", "SortingMethod": "Natural"},
      {"DimensionId": "Month", "SortBy": "Code", "SortingMethod": "Natural"}
    ],
    "ValueTypes": {"SortBy": "Name", "SortingMethod": "Natural",
                   "Items": [{"ValueTypeId": "Amount", "Aggregation": "Sum", "SpreadOverride": 0}]},
    "RowLevelAccess": {"$type": "Inherit", "EnableDimensionBasedAccess": false, "ReadOnly": false}
  }],
  "Workspaces": [{
    "Id": 1, "Name": "Budget entry", "Hidden": false,
    "Filters": [{"$type": "ValueType"}, {"$type": "DataType"}],
    "ActionComponents": [],
    "DataTypes": {"PlanData": {"Value": "Selected", "UsePlanName": false}},
    "ValueTypes": {},
    "Layout": {"$type": "MultiPage", "Pages": [{
      "HideInPageSelector": false,
      "MainComponent": {
        "$type": "Grid", "Id": "1", "Name": "Budget", "DatasetId": 1,
        "RowTotal": "Left", "AutoSizeStrategy": "Default", "HideHeader": false,
        "EnableColumnTotals": true, "EnableUserConfig": true, "EnableComments": true,
        "Groupings": [],
        "Intermediaries": [{"$type": "Dimension", "DimensionId": "Account",
                            "Settings": {"$type": "Intermediary", "EnableEdit": false}}],
        "Pivots": [{"$type": "Dimension", "DimensionId": "Month",
                    "Settings": {"$type": "Pivot", "SortDirection": "Ascending"}}]
      }}]}
  }],
  "Access": {"Locked": false, "Enabled": true}
}
```

!!! agent "For agents"
    The safe editing order (`get_app_config_schema` → get → modify → validate → set → read back) and the known pitfalls — enum codes, `$type` versus `Type`, colours without `#`, silently removed icons — are in the [Agent guide](agent-pitfalls.html#app-configuration).

## Element reference

| Element (XML) | JSON | Purpose | Key attributes | See |
|---|---|---|---|---|
| `App` | `AppConfigModel` | root | `SchemaVersion` | [Apps](apps.html) |
| `Access` | `Access` | app access | `Locked`, `Enabled`, `AccessListId` | [Apps](apps.html#app-access) |
| `DataSet` | `Datasets[]` | dataset | `Id`, `Name` | [Datasets](datasets.html) |
| `Grouping` | `DatasetDimensions[]` | dimension or property in the dataset | `Value`, `DimTagGroupId`, `DimensionId`, `SortByDimValueNo`, `SortingMethod`, `DisplayFormatId` | [Datasets](datasets.html#the-dimensions-matrix) |
| `ValueTypes/ValueType` | `ValueTypes.Items[]` | value type in the dataset | `Value`, `Name`, `Aggregation`, `Condition`, `SpreadValue` | [Datasets](datasets.html#value-types-in-a-dataset) |
| `ExcludedDimensionValueDefaults/Code` | `ExcludedDimensionValueDefaults` | defaults for excluded dimensions | `DimensionId`, `Value` | [Datasets](datasets.html#dimensions-removed-by-aggregation) |
| `InitialValues/Set` | `InitialValues[]` | expansion rule | `Enabled`, `ExpandAllValueTypes`, `TakeFromDataSet` | [Datasets](datasets.html#initial-values) |
| `LockedValues/Set` | `LockedValues[]` | lock rule | `Enabled` | [Datasets](datasets.html#locked-values) |
| `Filters/Filter` | `DatasetFilter` | dataset filter | `DimensionId`, `DimTagGroupId`, codes | [Datasets](datasets.html#dataset-filter) |
| `Expressions/Dimensions/Expression` | `Expressions[]` | computed dimension value | `DimValueNo`, `DimValueName`, `Aggregation`, `Format`, `Precision`, `Language`, `OmitNullRows`, `Value`, `Writeback*` | [Datasets](datasets.html#expressions) |
| `InheritRowLevelAccess` / `LimitRowLevelAccess` | `RowLevelAccess` | row-level access | `EnableDimensionBasedAccess`, `AccessListId`, `ReadOnly` | [Datasets](datasets.html#row-level-access) |
| `Styles` | (`HasStyling`) | legacy dataset styling; preserved, not editable | | this page |
| `Workspace` | `Workspaces[]` | workspace | `Id`, `Name`, `Hidden` | [Components](components.html#workspaces) |
| `Workspace/Filter` | `Filters[]` | filter row | `IsRequired`, `Message`, `Max`, `AllRequired`, `RequiredComponent` | [Components](components.html#filters) |
| `PlanData`, `References/Reference`, `DataTypeSortOrder` | `DataTypes` | data types offered | `Value`, `UsePlanName`, `Id`, `Selected` | [Components](components.html#data-types-and-references) |
| `Workspace/ValueTypes`, `ValueTypeSortOrder` | `ValueTypes` | value type names and order | `Id`, `Name` | [Components](components.html#value-types) |
| `Layout` | `Layout` | layout | `Type` | [Components](components.html#layouts) |
| `Page` | `Pages[]` | page in a multi-page layout | `Hidden` | [Components](components.html#layouts) |
| `MatrixComponent`, `Location` | `Components[]`, `Location` | component placement | `X`, `Y`, `Width`, `Height`, `Hidden` | [Components](components.html#layouts) |
| `LayoutSettings` | `Settings` | grid layout styling | `Spacing`, `BackgroundColor(DarkMode)`, `BorderColor(DarkMode)` | [Components](components.html#layouts) |
| `Component` | `AppComponent` | component | `Id`, `Name`, `Type`, `HideHeader` | [Components](components.html#component-types) |
| Grid `Filters/Set` | `Filters[]` | component filter | `Mode`, `Filter/@Type` | [Components](components.html#component-filters) |
| Grid column `Setting` | `ColumnSettings[]` | column settings | `Type`, `Value` / `Id`, `Width`, `Pinned` | [Components](components.html#column-settings) |
| `Rule` | `PresentationRules[]` | presentation rule | `Enabled`, `NameIndex`, `DefaultRuleKey`, `Name`, style attributes | [Components](components.html#presentation-rules) |
| `MetricComparison` | `Compare` | metric comparison | `Type`, `Mode`, colours | [Components](components.html#metric) |
| `ActionComponentGroup` | `ActionComponentGroup` | group of actions | `Id`, `Name`, `Description` | [Actions](actions.html#groups) |
| `ActionComponent` | `ActionComponent` | action | `Id`, `Name`, `RunButtonLabel`, `HideInSidebar`, `Script` | [Actions](actions.html) |
| `Variables/Text`, `Numeric`, `Dimension`, `Property` | `VariableInputs[]` | action variables | `Identifier`, `Name`, type-specific attributes | [Actions](actions.html#variables) |
| `LegacyActionComponents` | | legacy actions; removed in v2 plans | | [Actions](actions.html#legacy-action-components) |

### Presentation rule attributes

`NameIndex` is a random number from 0 to 19, set when a rule is created or copied. It only picks a placeholder name for the rule's preview in the editor. It has no other meaning. Default rules have `NameIndex="-1"` and a `DefaultRuleKey`. The name shown is `Name` if set, otherwise the label of the default rule key, otherwise the placeholder name.

Colour attributes come in pairs, `FontColor` / `FontColorDarkMode` and `BackgroundColor` / `BackgroundColorDarkMode`. In JSON they are grouped as `Styles.FontColor.{Light,Dark}`.

!!! note "Schema enum values not covered here"
    The JSON Schema defines some enum values (for example additional line states and line access `0`) that are internal or legacy and are deliberately not described in these docs. Do not use values that are not listed on the conceptual pages.

## Related

- [Apps](apps.html)
- [Datasets](datasets.html)
- [Workspaces and components](components.html)
- [Actions](actions.html)
- [AI agents](ai-agents.html)
