Data files & mappings

#Dataset formats

Database supports two dataset formats:

• JSON
• CSV

A dataset can be local or Git-synced.

#JSON

Supported shapes:

• array of objects (recommended),
• single object (handled as one-row dataset at apply/generate time).

Example:

[
  {
    "title": "Nike Air Max",
    "price": 129.9,
    "badge": true,
    "user": { "name": "Anna" }
  }
]

#JSON value resolution rules

When mapping resolves [path]:

1. direct key is checked first (important for flat keys like sport.name-ru),
2. then dot-path traversal is used (user.name),
3. if an intermediate value is an array and no numeric index is provided, the first element is used.

For object values inserted into text, the plugin uses this priority:

ru → en → default → value → text → title → name → JSON string fallback.

#CSV

CSV is parsed as header + data rows.

Rules used by SXL Studio parser:

• line 1 is header;
• minimum for parsed data is 2 lines (header + at least one row), otherwise result is empty;
• escaped quotes are supported ("");
• commas/new lines inside quoted values are supported;
• duplicate headers are renamed to name, name_2, name_3, ...

Type conversion:

• numeric strings are converted to numbers;
• strings with leading zeros (like 001) stay strings;
• empty strings stay empty strings;
• CSV values are not auto-cast to boolean by the CSV parser.

#CSV editor modes

For CSV datasets, the UI provides:

• Code mode: raw CSV editing,
• Table mode: grid editing.

Table mode features:

• rename columns,
• add/delete/duplicate rows,
• add columns,
• drag columns to reorder,
• single-column sorting,
• search filter,
• copy/copy all,
• paste CSV from clipboard (new columns are added automatically),
• empty rows/columns are removed on save.

#Assets

Supported upload formats:

• PNG, JPG/JPEG, GIF, WebP, SVG.

On upload, WebP/SVG are converted to PNG for local asset storage.

Image values in mapping can come from:

• https://... URL,
• data:image/... URL,
• local-asset://<assetId>,
• local asset name/path,
• Git file path.

HTTP URLs are rejected by image fetch logic. Use HTTPS URLs.

#Mapping JSON schema (.map.json)

A mapping file is stored as JSON with $type: "maps".

#Root keys

#FieldConfig keys

#Key Expression reference

#Base syntax

• Bracket path: [title]
• Dot path: [user.name]
• Multiple keys: [first] [last]
• Bare key (without brackets) is also accepted and treated as [key]

#Concatenation with +

[a] + [b] is treated as direct concatenation between placeholders.

#Remove modifier

Use - (space-dash-space):

• [status] - prefix_ → removes prefix_
• [code] - *- → removes everything up to last -

#Embedded placeholders in dataset values

After normal expression evaluation, the plugin also resolves embedded [path] inside resulting string values if the path exists in the same row.

Example:

• dataset value: "Total [fts] (NP)"
• fts = 7.5
• result: "Total 7.5 (NP)"

#Target Layer matching

A node is a target when either of these matches mapping layerName:

• node name,
• TEXT characters.

Normalization used for matching:

• trim edges,
• replace NBSP with regular spaces.

Matching remains case-sensitive.

#Dataset selection priority

For each field, dataset resolution order is:

1. field.datasetId
2. mapping.datasetId
3. auto-detection by expression keys against first row of datasets
   • full key match preferred,
   • partial match fallback.

#Fill behavior

#fillStrategy (field-level)

• asc: forward order,
• desc: reverse order,
• random: random row.

#groupFillMode (group-level)

• same: per-container local counters,
• global: one shared counter across containers,
• random: random row per group application.

#Directives reference

Directives are string values in dataset cells.

#@prop: (component properties)

Syntax:

@prop:Property=value
@prop:Visible=true;Label=New

Notes:

• supports multiple props separated by ;,
• escaped semicolon is supported as \;,
• applied to INSTANCE targets only,
• available when PROP control feature is enabled.

#@node: / @hide / @show

Supported node directives:

• @hide → visible=false
• @show → visible=true
• @node:visible=true|false
• @node:opacity=0..1
• @node:locked=true|false

Notes:

• multiple node directives can be chained with ;,
• for TEXT targets, visibility directives typically apply to the parent container,
• available when Node control feature is enabled.

#@rows: and $visibleRows / $rows

• @rows:3 shows first 3 children and hides the rest on the target container.
• Numeric values coming from expressions with $visibleRows or $rows are also supported.

Note: this logic is skipped for native SLOT nodes.

#Plain boolean values on INSTANCE targets

If the mapped value is boolean-like (true/false/1/0/yes/no/on/off) and target is INSTANCE, the plugin sets the first BOOLEAN component property on that instance.

#Example mapping file

{
  "$type": "maps",
  "id": "map_cards",
  "name": "cards.map.json",
  "createdAt": "2026-05-27T10:00:00.000Z",
  "updatedAt": "2026-05-27T10:05:00.000Z",
  "datasetId": "ds_products",
  "targetComponentKey": "2b8b2...",
  "targetComponentName": "WProductCard",
  "autoHideUnused": true,
  "fields": [
    {
      "id": "f_title",
      "jsonPath": "[title]",
      "layerName": "product-title",
      "fillStrategy": "asc",
      "group": "card/content",
      "groupFillMode": "same"
    },
    {
      "id": "f_badge",
      "jsonPath": "@prop:Visible=[badge]",
      "layerName": "badge",
      "fillStrategy": "asc"
    }
  ]
}

#Related pages

• Operations and runtime behavior: Apply & Generate
• General Database workflow: Database overview