> For the complete documentation index, see [llms.txt](https://codifi-fdm.gitbook.io/codifi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codifi-fdm.gitbook.io/codifi-docs/web-app/map-setup-and-offline-areas/map-overlays/styles/json-styling.md).

# JSON Styling & the Mapbox Spec

The **JSON tab** of the [Map Style Editor](/codifi-docs/web-app/map-setup-and-offline-areas/map-overlays/styles.md) shows the raw style document underlying everything you see on the Layers tab. It's the underlying source of truth — every visual control on the Layers tab edits this JSON, and every change you make in the JSON tab reflects back on the Layers tab when you switch back.

Use the JSON tab when:

* You need an expression or property the visual builders don't expose.
* You're copy-pasting a style from another Project, a Mapbox Studio export, or an AI-generated draft.
* You're authoring at the speed of typing, not clicking.
* You want to inspect exactly what the editor is producing.

You don't *have* to use the JSON tab — every common style is fully achievable from the Layers tab. But the JSON tab is the escape hatch for anything that isn't.

***

## What the JSON Looks Like

Each layer in the Map Style Editor maps to one entry in the JSON's `layers` array, in Mapbox style spec format:

```json
{
  "id": "site-fill",
  "type": "fill",
  "source": "overlay-source",
  "filter": ["==", ["get", "archetype"], "Site"],
  "paint": {
    "fill-color": [
      "match",
      ["get", "siteType"],
      "Habitation", "#E63946",
      "Lithic Scatter", "#3498DB",
      "#7F8C8D"
    ],
    "fill-opacity": 0.4
  },
  "layout": {
    "visibility": "visible"
  }
}
```

* **`id`** — unique identifier for the layer.
* **`type`** — one of the layer types from the [Layers & Properties](/codifi-docs/web-app/map-setup-and-offline-areas/map-overlays/styles/layers-and-properties.md) reference (`circle`, `line`, `fill`, `symbol`, `heatmap`, `fill-extrusion`).
* **`source`** — where the data comes from. Set automatically by Codifi for overlays and archetypes.
* **`filter`** — optional expression that excludes features from this layer.
* **`paint`** — visual properties (colors, widths, opacities, dashes).
* **`layout`** — non-visual properties (visibility, line cap/join, text font, icon image).

***

## Linking to the Mapbox Style Spec

Codifi's Map Style Editor implements the **Mapbox Style Specification** (compatible with both Mapbox GL JS and MapLibre). For the canonical reference on every property, every expression, and every layer type, use the Mapbox spec:

| Topic                                  | Reference                                                                                                                |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Style spec overview**                | [docs.mapbox.com/style-spec](https://docs.mapbox.com/style-spec/reference/root/)                                         |
| **Layers**                             | [Layer reference](https://docs.mapbox.com/style-spec/reference/layers/)                                                  |
| Circle layer (Point)                   | [`circle`](https://docs.mapbox.com/style-spec/reference/layers/#circle)                                                  |
| Line layer (Line, Polygon Outline)     | [`line`](https://docs.mapbox.com/style-spec/reference/layers/#line)                                                      |
| Fill layer (Polygon)                   | [`fill`](https://docs.mapbox.com/style-spec/reference/layers/#fill)                                                      |
| Symbol layer (Marker, Label)           | [`symbol`](https://docs.mapbox.com/style-spec/reference/layers/#symbol)                                                  |
| Heatmap layer (Point density)          | [`heatmap`](https://docs.mapbox.com/style-spec/reference/layers/#heatmap)                                                |
| 3D Extrusion (Polygon volumes)         | [`fill-extrusion`](https://docs.mapbox.com/style-spec/reference/layers/#fill-extrusion)                                  |
| **Expressions** (data-driven values)   | [Expression reference](https://docs.mapbox.com/style-spec/reference/expressions/)                                        |
| `match`, `case`, `interpolate`, `step` | Linked from the expression reference                                                                                     |
| **Sources**                            | [Source reference](https://docs.mapbox.com/style-spec/reference/sources/) (advisory — Codifi sets sources automatically) |

Bookmarking the Layer reference is the highest-leverage move: every property name in your style JSON has its full description, valid value range, and version compatibility on that page.

***

## Working in the JSON Tab

* **Auto-validation** — the editor checks your JSON as you type. Syntax errors show inline, and the Save button stays disabled until the document is valid.
* **Round-trip with Layers tab** — switch back to Layers and the visual editors reflect what you typed. If you author an expression that matches one of the visual builders' known patterns (a Match, a Case, an Interpolate), the visual builder picks it up; if not, the property shows as a Raw expression.
* **Don't change the `source`** — Codifi manages the source for overlays and archetypes. Edit `paint`, `layout`, `filter`, layer order, and IDs freely; leave `source` alone.

***

## AI-Assisted Style Authoring

LLMs are surprisingly good at authoring Mapbox styles when given the right context. Here's a prompt template that works well:

```
I'm authoring a Mapbox-compatible style for a Codifi map overlay.
The geometry is [Point | Line | Polygon].
The features have these properties (with example values):
  - propertyA: "Site" | "Feature" | "Isolated Find"
  - propertyB: <numeric, range 0–500>
  - propertyC: <date>

I want the style to:
  - [describe the visual outcome]

Please give me one or more layer JSON entries in Mapbox style-spec format.
For each property that varies by attribute, use a "match", "case", or
"interpolate" expression. Reference field IDs as ["get", "fieldName"].
Keep the source set to "overlay-source" — I'll let Codifi handle the source.
```

Paste the result into the JSON tab. The visual editor will pick up any patterns it recognizes, so you can keep editing in either tab from there.

***

## Things the JSON Tab Won't Let You Do

A few areas are explicitly managed by Codifi and aren't editable from the JSON tab:

* **The data source itself** — Codifi sets `source` automatically. You can change `source-layer` for vector-tile data sources but not the source URL.
* **Sprite and glyph URLs** — managed by Codifi to ensure offline icons and fonts work for mobile crews.
* **Style version** — locked to the version Codifi targets.

Edits to those fields will either be ignored or reverted on save.

***

## See Also

* [Layers & Properties](/codifi-docs/web-app/map-setup-and-offline-areas/map-overlays/styles/layers-and-properties.md) — visual editor reference, layer types, ordering
* [Data-Driven Styling](/codifi-docs/web-app/map-setup-and-offline-areas/map-overlays/styles/data-driven-styling.md) — visual builders for Match / Case / Interpolate / Filter
* [Mapbox Style Specification](https://docs.mapbox.com/style-spec/reference/root/) — the underlying spec for every property and expression