Barcode Scanner Settings JSON format

This document describes the JSON format understood by the sc_barcode_scanner_settings_new_from_json() function.

Format Overview

The top-level must always be a dictionary (object) containing one or more key-value pairs. In the simplest form, an empty dictionary can be passed to the function. This will return a default barcode scanner settings instance with all symbologies disabled. All other properties have their default value. In general, missing properties are left at their default value, so only the properties that need to be changed away from their default need to be specified. Key-value pairs not understood the by JSON parser are ignored as if they were not specified.

Symbology Settings

By default, all symbologies are disabled. To enable a symbology, it must be listed under the "symbologies" key. Symbologies can either be a dictionary, or an array of symbology names:

"symbologies" : [ "ean13", "upca", "code128" ]

When using a dictionary, further symbology options can be specified, such as extensions to enable, used checksums etc.:

"symbologies" : {
"ean13" : true,
"upca" : {
"extensions" : ["remove_leading_zero"]
"itf" : {
"checksums" : [ "mod10" ]

The following options are currently supported:

  • enabled: boolean indicating whether the symbology should be enabled. When using the dictionary form, enabled is automatically set to true.
  • colorInvertedEnabled: boolean indicating whether color-inverted codes of that symbology should be decoded. Default is false.
  • activeSymbolCounts: array of integers specifying the active symbol counts for the symbology. See sc_symbology_settings_set_active_symbol_counts for details.
  • extensions: Extensions to be enabled for the symbology.
  • checksums: List of optional checksums to use for the symbology.

Depending on the symbology, some of these properties are ignored. See Symbology Properties for details.

The following table shows the symbology names understood by the JSON parser.

Symbology JSON Name (case is ignored)
EAN13 ean13
UPCA upca
EAN8 ean8
UPCE upce
Two-Digit-Add-On two-digit-add-on
Five-Digit-Add-On five-digit-add-on
MSI-Plessey msi-plessey
DataBar 14 databar
DataBar Expanded databar-expanded
DataBar Limited databar-limited
Codabar codabar
Code 11 code11
Code 32 code32
Code 39 code39
Code 93 code93
Code 128 code128
Standard 2 of 5 (Code 25) code25
Interleaved 2 of 5 itf
DataMatrix data-matrix
Aztec aztec
PDF417 pdf417
MicroPDF417 micropdf417
MaxiCode maxicode
QR qr
Micro QR microqr
KIX kix
RM4SCC rm4scc
DotCode dotcode

Code Location and Search Area

Note: These options are not available when constructing the ScanSettings object for a barcode picker from JSON. Use areaSettingsPortrait, areaSettingsLandscape instead.

To customize the search area and code location hints, you can use the codeLocation1d, codeLocation2d, searchArea and codeDirectionHint properties.

  • To customize the search area, set the searchArea property by defining the rectangle with x, y, width, and height. Example:
    "searchArea" : {
    "x" : 0.0, "y" : 0.0, "width" : 1.0, "height" : 0.5
  • To customize code location 1d and code location 2d, use the codeLocation1d and codeLocation2d properties. They consist of a rectangle, the area, and a constraint. Example:
    "codeLocation1d" : {
    "area" : {"x" : 0.0, "y" : 0.0, "width" : 1.0, "height" : 0.5 },
    "constraint" : "restrict" // or "hint"
    Constraint must either be "restrict", or "hint".
  • To customize the code direction hint, use the codeDirectionHint property. Example:
    "codeDirectionHint" : "left-to-right"
    The code direction hint must either be "left-to-right", "right-to-left", "bottom-to-top", "top-to-bottom", "none", "vertical", or "horizontal"

Other Properties