Skip to main content

Data lists — import, export, and includeLocales

Data list choice labels are stored as a JSON map (Labels) with a synthetic default key plus optional culture codes from the list’s AvailableLocales catalog.

Management list and items grids​

Parent list search uses the management list query string (search + page / pageSize). Item grids intentionally keep query (not search) to match the public runtime search contract (matchMode / locale / includeLocales). Hub UI may still expose a search box; the list maps it to API search, item grids to API query.

  • GET /api/data-lists?search=&hasLocale=&page=&pageSize= — name/description contains search; hasLocale is a culture or comma-separated OR list matching AvailableLocales or DefaultLocale.
  • GET /api/data-lists/{id}?includeItems=false — catalog metadata and itemsCount without loading item rows.
  • GET /api/data-lists/{id}/items?query=&matchMode=&locale=&includeLocales=&page=&pageSize= — paged item search for authors (inactive lists included). Default pageSize is 25.

There is no per-item POST/PATCH/DELETE. Authors replace the file with import/export below.

Import / export (management)​

Authenticated authors round-trip items with a single import and export surface. Format is negotiated in the JSON body (format), same pattern as submissions export.

  • PUT /api/data-lists/{id}/import — body { "format": "json" | "csv", ... }
  • POST /api/data-lists/{id}/export — body { "format": "csv" | "json" }

Import​

JSON (format: "json", default):

{
  "format": "json",
  "items": [
    { "value": "apple", "labels": { "default": "Apple", "fr": "Pomme" } }
  ],
  "ensureLocales": ["fr"]
}

CSV (format: "csv"):

{
  "format": "csv",
  "csv": "value,default,fr\r\napple,Apple,Pomme\r\n",
  "ensureLocales": ["fr"]
}

Optional ensureLocales adds those cultures to AvailableLocales before validating label keys / CSV columns (idempotent). Hub shows a discovery dialog so authors select which new locales to ensure. Deselected locale columns are stripped from the CSV/JSON before upload.

Export​

  • format: "csv" (default) — RFC 4180 translations CSV (text/csv attachment)
  • format: "json" — array of { value, labels } (application/json attachment)

CSV shape (RFC 4180)​

Header (required):

value,default,{locale…}

Example:

value,default,fr,de
apple,Apple,Pomme,Apfel
pear,Pear,Poire,Birne

Rules:

  • Rows are keyed by the invariant value column.
  • A default column is required. Locale columns must be in the data list AvailableLocales catalog (or resolve to default).
  • Empty cells clear that locale key for the row on import.
  • Unknown locale columns and over-long labels are rejected with validation errors.
  • Hub client discovery mirrors API culture rules: lowercase BCP-47-shaped keys (en-us, not en-US).
  • Culture keys in Labels / CSV headers are normalized to lowercase on write.

Public search and display-values​

Public endpoints (form-access JWT):

  • GET .../public/forms/{formId}/data-lists/{dataListId}/search
  • GET .../public/forms/{formId}/data-lists/{dataListId}/display-values

includeLocales​

Pass one or more locales as repeated query params (includeLocales=default&includeLocales=fr) or a comma-separated value. Locales outside the catalog are ignored. default is always included in the projected labels map.

Search also uses the optional locale query parameter to pick the primary display/sort label key (and that key is searchable). Projection for nested labels on search includes default, the resolved locale key when present, and any includeLocales.

Response shape​

Choices use Endatix value + labels (same map as the domain). Hub maps labels → SurveyJS text at the form runtime boundary:

{
  "value": "apple",
  "labels": { "default": "Apple", "fr": "Pomme" }
}

labels always includes default and any projected culture keys from locale / includeLocales. Monolingual lists use the same shape with only default.

Search behavior​

With a free-text query, matching uses MatchMode (Contains / StartsWith / Exact) against:

  1. The invariant value
  2. The resolved locale label key (Labels["default"] when locale is omitted / default)
  3. Label paths for locales listed in includeLocales

Locales that are not requested (and are not the active locale) are not searched, so omitted locales do not pollute results.