> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/help/ja/llms.txt)

# Migrate from Mapbox Streets v7 to v8

If you are using a map style built with the Mapbox Streets v7 tileset, we highly recommend migrating to Mapbox Streets v8. **Mapbox Streets v7 will stop receiving data updates on September 1, 2021.** Mapbox Streets v8 also contains many improvements including additional data fields and refactored layers designed to be used with [expressions](https://docs.mapbox.com/style-spec/reference/expressions/) (as described in the Mapbox Style Specification) and compatibility with [style components](https://medium.com/mapbox/style-components-in-studio-77cc2f98815b).

Because there are [significant structural changes](https://docs.mapbox.com/vector-tiles/reference/mapbox-streets-v8/#changelog) between v7 and v8, swapping the source URL with `mapbox-streets-v8` without adjusting source layer names, filters, and style properties that rely on data fields will result in style errors. This guide will help you decide on an appropriate approach to migrating your map style and provide tips for making the switch.

> **Note: Complete reference documentation**
> 
> You can find additional information on Mapbox Streets v8, including detailed descriptions of available source layers and fields, in the [vector tile reference](https://docs.mapbox.com/vector-tiles/reference/mapbox-streets-v8/).

## Options for migrating

There are two suggested options for migrating your style to use v8 data:

-   **Option 1**: If you built your style on top of an older version of a template style (like Streets, Light, Outdoors, etc.) and made a few custom edits, it's recommended to recreate a style using the newer version of the template. Our latest styles use Mapbox Streets v8 and style components, and are designed to be tweaked in Studio.
-   **Option 2**: If you built your style from scratch using the Mapbox Streets tileset, or if you made a significant number of edits to an older template style, you can create a migrated copy of your style in Mapbox Studio using an automated workflow.

Choose an option that most closely matches your situation, and follow the steps below:

### Option 1: Create a custom style

1.  In Studio, create a new style using the Mapbox Standard style.
2.  Add any additional layers and configuration options for Mapbox Standard.
3.  When you're ready, publish your style and use the new style URL in your implementation.

> **Related content (tutorial): [Create a custom style](https://docs.mapbox.com/help/ja/tutorials/create-a-custom-style/)**
> 
> See how to create a custom style with Mapbox studio.

### Option 2: Use an automated workflow

You can create a migrated copy of your style using an automated workflow, which will update all layers using Mapbox Streets v7 to use v8 while preserving visual characteristics, SDK requirements, and layer names. Migrated styles may show some variations due to changes in underlying data, such as higher label density for points of interest.

![Comparing versions in the automated update workflow.](https://docs.mapbox.com/help/ja/assets/ideal-img/troubleshooting--streets-v8-migration-guide--automated-workflow.4d9fb91.480.png)

If possible, we recommend updating to expressions at the same time you update a style to Mapbox Streets v8. Though styles using expressions have higher SDK requirements, access to expressions will improve the quality of the Mapbox Streets v7 to v8 migration.

## Important tips to know

Here are some important tips to know.

### Do not mix Mapbox Streets v7 and v8

Mixing different versions of the same source is not recommended, because layer names are reused across versions. In Mapbox Studio, if you try to use Mapbox Streets v8 when layers in your style already use Mapbox Streets v7, you will see a warning message:

![A warning message for incompatible vector layer names in Studio.](https://docs.mapbox.com/help/ja/assets/ideal-img/troubleshooting--streets-v8-migration-guide--source-warning.0c70870.480.png)

### Migrate from property functions to property expressions

Template styles built with Mapbox Streets v7 use [property functions](https://docs.mapbox.com/style-spec/reference/other/#function) (left) for zoom and data styling. We highly recommend using the [expressions](https://docs.mapbox.com/style-spec/reference/expressions/) syntax (right) for more flexibility and longevity. Expressions syntax and the deprecated property function syntax cannot be mixed in a single style property or filter definition.

![A comparison of a filter with older syntax vs. newer syntax.](https://docs.mapbox.com/help/ja/assets/ideal-img/troubleshooting--streets-v8-migration-guide--filter-syntax.fded218.480.png)

Studio displays filters slightly differently for values that use property functions instead of expressions. The older interface displays different sections for each type of filter (left). For newer, expression-based filters, options for geometry type and field values have been combined into a single panel (right).

![A comparison of the Studio UI with older filters vs. newer filters.](https://docs.mapbox.com/help/ja/assets/ideal-img/troubleshooting--streets-v8-migration-guide--filter-ui.95e80d4.480.png)

The value for any layout property, paint property, or filter may be specified as an expression. To automatically update all your property functions to use expressions, you can create an updated copy of your style under `Settings` in Studio.

![A button for creating a migrated copy in Studio.](https://docs.mapbox.com/help/ja/assets/ideal-img/troubleshooting--streets-v8-migration-guide--create-migrated-copy.1d283d8.480.png)

### Avoid broken `name-*` fields

Unlike previous versions of Mapbox Streets, when using Mapbox Streets v8 you **must add fallback languages manually** to avoid broken labels.

In Mapbox Streets v7 (left), if a translation is not available for one of a feature's `name_*` fields (for example, `name_en` and `name_fr`), the value of the `name` field is used as a fallback. In Mapbox Streets v8 (right), if a translation is not available, the value will be `null`. This allows you to customize your fallback preferences using expressions.

![A comparison of the name field without a fallback vs. the name field with a fallback.](https://docs.mapbox.com/help/ja/assets/ideal-img/troubleshooting--streets-v8-migration-guide--name-field.511b7d3.480.png)

The underlying expression looks like this:

```json
"text-field": ["coalesce", ["get", "name_en"], ["get", "name"]]
```

## Data changes

The following sections highlight data layers that require special attention while migrating.

### Renamed source layers

The data in the following source layers were renamed, but the underlying data is largely the same between v7 and v8. When migrating, you can replace the `source` and `source-layer` without adding new filters or changing style properties.

| Streets v7 source layer | Streets v8 source layer |
| --- | --- |
| `barrier_line` | `structure` |
| `rail_station_label` | `transit_stop_label` |

### Condensed source layers

The data in the following source layers have been condensed into a single source layer. Data-driven styling with expressions makes it possible to style features according to data properties from a single source layer.

[`place_label`](https://docs.mapbox.com/vector-tiles/reference/mapbox-streets-v8/#place_label) contains points for labeling places including countries, states, cities, towns, and neighborhoods. This layer existed in Mapbox Streets v7, but it contained only "human settlements" like cities and neighborhoods. In Mapbox Streets v8, it also contains country and state labels.

| v7 source layer | v8 source layer | Suggested filter |
| --- | --- | --- |
| `country_label` | `place_label` | `class` = `country` |
| `state_label` | `place_label` | `class` = `state` |

[`natural_label`](https://docs.mapbox.com/vector-tiles/reference/mapbox-streets-v8/#natural_label) contains points and lines for styling natural features such as bodies of water, mountain peaks, valleys, deserts, and more. This layer is new in Mapbox Streets v8, but the data it contains existed in different layers in v7.

| v7 source layer | v8 source layer | Suggested filter |
| --- | --- | --- |
| `marine_label` | `natural_label` | `class` = `ocean`, `sea`, `bay` |
| `mountain_peak_label` | `natural_label` | `class` = `landform` |
| `water_label` | `natural_label` | `class` = `water` |
| `waterway_label` | `natural_label` | `class` = `river`, `canal`, `stream` |

[`road`](https://docs.mapbox.com/vector-tiles/reference/mapbox-streets-v8/#road) contains lines, points, and polygons needed for drawing features such as roads, railways, paths and their labels. This layer existed in Mapbox Streets v7, but it was only appropriate for creating line layers. In Mapbox Streets v8, it can also be used for symbol layers.

| v7 source layer | v8 source layer | Suggested filter |
| --- | --- | --- |
| `road_label` | `road` | None, but be sure to use `type` = `symbol` |

### `admin` boundaries

Mapbox Streets v8 uses slightly different [`admin`](https://docs.mapbox.com/vector-tiles/reference/mapbox-streets-v8/#admin) boundary division definitions. Before, v7 used values of `2`, `3`, and `4`, while Streets v8 uses values of `0`, `1`, and `2`. Note the different descriptions below.

| v7 `admin` value |  | v8 `admin` value |  |
| --- | --- | --- | --- |
| `2` | Countries | `0` | Countries |
| `3` | Some subnational regions or groupings: regions of Papua New Guinea, The Philippines, Venezuela; governorates of Lebanon; federal districts of Russia; some disputed and semi-autonomous regions | `1` | First-level administrative divisions |
| `4` | Most first-level subnational boundaries (states, provinces, etc.) | `2` | Second-level administrative divisions |

There is also a new [`worldview` field](https://docs.mapbox.com/vector-tiles/reference/mapbox-streets-v8/#worldview-text) that provides an option to cater boundary lines to different locales. You can use either US, CN, IN, or JP to show the United States', China's, India's, or Japan's opinions of global and disputed borders.

### `sizerank`, `filterrank`, and `symbolrank`

In v7, the `scalerank` and `localrank` fields were used to rank features. These fields are not included in v8. Instead, v8 introduces three new fields for ranking features: [`sizerank`](https://docs.mapbox.com/vector-tiles/reference/mapbox-streets-v8/#sizerank-number), [`filterrank`](https://docs.mapbox.com/vector-tiles/reference/mapbox-streets-v8/#filterrank-number), and [`symbolrank`](https://docs.mapbox.com/vector-tiles/reference/mapbox-streets-v8/#--place_label---symbolrank-number). **The ranking fields in v8 are fundamentally different than the ranking fields in v7, but can be used to generate similar effects.**

<table><thead><tr><th>Commonly used for</th><th>v7 field</th><th>Relevant v7 layers</th><th>v8 field</th><th>Relevant v8 layers</th></tr></thead><tbody><tr><td>Customizing label density</td><td><code>localrank</code><div class="txt-s">(number &gt; 0)</div></td><td><code>place_label</code><br><code>poi_label</code></td><td><code>filterrank</code><div class="txt-s">(number 0-5)</div></td><td><code>place_label</code><br><code>poi_label</code><br><code>natural_label</code></td></tr><tr><td>Styling labels based on relative prominence</td><td><code>scalerank</code><div class="txt-s">(number 1-6 or <code>null</code>)</div></td><td><code>place_label</code><br><code>poi_label</code><br><code>airport_label</code></td><td><code>symbolrank</code><div class="txt-s">(number 0-16)</div></td><td><code>place_label</code></td></tr><tr><td>Styling labels based on relative physical size of the feature</td><td>—</td><td>—</td><td><code>sizerank</code><div class="txt-s">(number 1-19)</div></td><td><code>poi_label</code><br><code>airport_label</code><br><code>natural_label</code></td></tr></tbody></table>

Because there is not a one-to-one relationship between fields used to rank features in v7 and v8, there is no simple transformation from one to the other. The maps below allow you to explore the relationship between these fields.

#### Customize label density

The v8 field `filterrank` is a value from 0-5 used that helps customize label density. When rebuilding your layers in the `[v8]` version of your style, set `filterrank <= 1` to only show the most prominent labels, `filterrank <=3` to produce moderate density, or `filterrank <= 5` to see as many labels as possible.

There is no one-to-one relationship between v7's `localrank` and v8's `filterrank`, but their effect is similar. Use the maps below to explore the relationship between `localrank` and `filterrank`. Notice that `localrank` and `filterrank` vary across zoom levels.

#### Filter by feature prominence

The v8 field `symbolrank` is a number between 0-16 that helps simplify styling of the label size and symbol prominence of place features. When rebuilding your layers in the `[v8]` version of your style, use `symbolrank <= 1` to apply a bold style to only the most prominent features or use `symbolrank` with expressions to hide and show features of a specific prominence at various zoom levels.

There is no one-to-one relationship between v7's `scalerank` and v8's `symbolrank`, but their effect is similar. Use the maps below to explore the relationship between `scalerank` and `symbolrank`. Notice that the value of a feature's `scalerank` or `symbolrank` field persists across zoom levels.

#### Filter by physical size

The v8 field `sizerank` is used for label layers where points or lines have been derived from polygons. The largest areas are ranked `sizerank=0`, and the smallest points are ranked `sizerank=16`. This is a new concept in v8 (v7 did not include a field with this kind of information) so you can use it as you see fit when creating new layers in the `[v8]` version of your style.

### `class` field in `poi_label`

In the `poi_label` layer, a new `class` field contains thematic categories that are useful for filtering and symbol styling. There are also many new `maki` options for use with our [Maki iconset](https://labs.mapbox.com/maki-icons/).

![A list of many of the available maki values for points of interest.](https://docs.mapbox.com/help/ja/assets/ideal-img/troubleshooting--streets-v8-migration-guide--maki.d366592.480.png)

## Use the same style URL

Rebuilding your style with a new template or migrating your style to use expressions will generate a new [style URL](https://docs.mapbox.com/help/ja/glossary/style-url/). If you want to keep your existing style URL, use the `Replace` option in Studio.

![A button for replacing a style with an uploaded file in Studio.](https://docs.mapbox.com/help/ja/assets/ideal-img/troubleshooting--streets-v8-migration-guide--replace-style.c0dd439.480.png)

The file you upload must be a JSON document adhering to the [Mapbox Style Specification](https://docs.mapbox.com/style-spec/). Additionally, the style must contain a [sprite URL](https://docs.mapbox.com/style-spec/reference/sprite/) referencing all icons and images used in the style, and a [glyph URL](https://docs.mapbox.com/style-spec/reference/glyphs/) referencing all fonts used in the style. You cannot replace a style with one that does not reference the correct sprite or glyph URL.

Replacing a style cannot be undone, so before replacing, make sure the style is working correctly. You may also want to duplicate the style before replacing it to have a backup.