style.json

About

style.json files are used to define base map styles in Carto Mobile SDK. They correspond roughly to the project.yaml files of MapBox Studio Classic. Though the main styling is done using CartoCSS, there are aspects like layer ordering and external style parameters (nutiparameters) that can not be expressed using CartoCSS. The following sections describe the structure of the style.json

Layers

The 'layers' section contains the list of layers in reverse rendering order. For OMT schema, typically the following structure is used:

  "layers": [
    "housenumber",
    "transportation_name",
    "water_name",
    "poi",
    "place",
    "transportation",
    "building",
    "aeroway",
    "waterway",
    "water",
    "boundary",
    "park",
    "landuse",
    "landcover"
  ]

Styles

The 'styles' section contains the list of CartoCSS files (.mss) used by the style. The ordering of the files is usually important, as this defines the order how the files are loaded and parsed.

An example:

  "styles": [
    "voyager/style.mss",
    "voyager/admin.mss",
    "voyager/hydro.mss",
    "voyager/landuse.mss",
    "voyager/roads.mss",
    "voyager/labels.mss"
  ]

Nutiparameters

Nutiparameters define style parameters that can be controlled from the applications. These parameters are typed and contain default values.

An example:

  "nutiparameters": {
    "lang": { "default": "en" },
    "markers3d": { "default": "nutibillboard", "values": {
      "0": "point",
      "1": "nutibillboard"
    } }
  }

This example defines 2 nutiparameters: "lang" and "markers3d". The "lang" parameter has the value "en" (string) by default, though this can be controlled from the code. The "markers3d" parameter is an enumeration parameter, it has 2 possible values "0" (which is internally converted to "point" value) and "1" (which is converted to "nutibillboard"). The default value is "nutibillboard". The following parameter types are supported: booleans, integers, floating point numbers and strings. JSON arrays or objects are not supported.

Files

Files section is used to track changes in all the files the style uses. Each referred file under this section includes basic metainfo about the file, like size and hash. Mobile SDK uses this section to allow incremental style updates. Only files that have changed are downloaded from the style server. Typically style changes do not involve font or image changes and only .mss files need to be downloaded.

Example:

files: {
  "voyager/style.mss": {
    "size": 8232,
    "md5": "891d3da23988dc4c941a490abd399125"
  },
  ...
}

Two fields are required for each file: 'size' and 'md5'. The value of 'md5' is the lowercase hexadecimal value of the MD5 hash of the file contents.

Other entries

The style.json files typically contain also 'name' field that stores the readable name of the style. This field is currently not used by SDK, though.