JSON objects as dictionaries

Introduction

As an alternative to using Excel workbooks to specify dictionary data, the platform also allows the use of JSON for this purpose. This is a simpler and preferred alternative if, e.g., data is pushed to the dictionary APIs programmatically from other systems. The structure of the JSON object is identical to the structure of the Excel workbook:

• The JSON object corresponds to an Excel workbook.

• Each top-level key in the JSON object corresponds to a worksheet in the workbook.

• The same naming conventions as for Excel worksheets apply. This defines if a sheet contains dictionary data (a "data worksheet") or dictionary meta data (a "property worksheet"). The naming conventions for worksheets are documented here. Note that:

  • Although for Excel worksheets it is currently required that their names start with @@, this is optional for the top-level JSON keys.

  • As with Excel worksheet names, some applications might require that the top-level JSON keys start with a customer prefix.

• For property worksheets, the same property names and property values apply for both JSON and Excel formats. The property names and property values are documented here.

• For data worksheets, a key maps to zero or more values. This is the same for both JSON and Excel formats.

Examples

$ cat mydictionary.json | jq .
{
  "xyz-colors": {
    "pear": "green",
    "orange": "orange",
    "apple": [
      "green",
      "red"
    ],
    "coconut": "brown",
    "banana": [
      "yellow",
      "brown"
    ]
  },
  "global-properties": {
    "unique-count": 1,
    "count": 2,
    "swap-fields": true,
    "value-normalization-flags": 4,
    "key-normalization-flags": 4,
    "mode": "overlap",
    "tokenizer-context": "en"
  }
}

Last updated: June 25, 2026