0
# Mapbox GL Style Specification
1
2
The Mapbox GL Style Specification package provides comprehensive tools for working with Mapbox GL style specifications. It includes validation, migration, formatting, expression evaluation, feature filtering, and CLI tools for style manipulation. This package serves as the foundation for creating, validating, and transforming Mapbox GL styles programmatically.
3
4
## Package Information
5
6
- **Package Name**: @mapbox/mapbox-gl-style-spec
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @mapbox/mapbox-gl-style-spec`
10
11
## Core Imports
12
13
```typescript
14
import {
15
validate,
16
format,
17
migrate,
18
expression,
19
featureFilter,
20
Color,
21
latest,
22
v8,
23
diff,
24
composite,
25
derefLayers,
26
visit,
27
function as styleFunction,
28
convertFilter,
29
ValidationError,
30
ParsingError,
31
validateMapboxApiSupported
32
} from "@mapbox/mapbox-gl-style-spec";
33
```
34
35
For CommonJS:
36
37
```javascript
38
const {
39
validate,
40
format,
41
migrate,
42
expression,
43
featureFilter,
44
Color,
45
latest,
46
v8,
47
diff,
48
composite,
49
derefLayers,
50
visit,
51
function: styleFunction,
52
convertFilter,
53
ValidationError,
54
ParsingError,
55
validateMapboxApiSupported
56
} = require("@mapbox/mapbox-gl-style-spec");
57
```
58
59
## Basic Usage
60
61
```typescript
62
import { validate, format, migrate, latest } from "@mapbox/mapbox-gl-style-spec";
63
64
// Validate a style
65
const styleObject = {
66
version: 8,
67
sources: {},
68
layers: []
69
};
70
71
const errors = validate(styleObject, latest);
72
if (errors.length === 0) {
73
console.log("Style is valid!");
74
} else {
75
console.error("Validation errors:", errors);
76
}
77
78
// Format a style with proper indentation
79
const formatted = format(styleObject, 2);
80
81
// Migrate an older style to current version
82
const migratedStyle = migrate(oldStyleObject);
83
```
84
85
## Architecture
86
87
The Mapbox GL Style Specification package is built around several key systems:
88
89
- **Validation System**: Comprehensive style specification compliance checking with detailed error reporting
90
- **Expression Engine**: Data-driven styling computation with zoom and feature-based expressions
91
- **Style Manipulation**: Tools for formatting, migration, diffing, and composition of styles
92
- **Feature Filtering**: Geometric and property-based filtering for map layers
93
- **Type System**: Complete TypeScript definitions for all style specification components
94
- **CLI Tools**: Command-line utilities for batch processing and automation workflows
95
96
## Capabilities
97
98
### Style Validation
99
100
Core validation functionality ensuring styles conform to the Mapbox GL specification. Provides detailed error reporting for debugging invalid styles.
101
102
```typescript { .api }
103
function validate(
104
style: StyleSpecification | string | Buffer,
105
styleSpec?: StyleReference
106
): ValidationError[];
107
108
class ValidationError {
109
message: string;
110
identifier?: string | null;
111
line?: number | null;
112
constructor(
113
key: string | null | undefined,
114
value: any,
115
message: string,
116
identifier?: string | null
117
);
118
}
119
120
class ValidationWarning extends ValidationError {}
121
122
class ParsingError {
123
message: string;
124
error: Error;
125
line: number;
126
constructor(error: Error);
127
}
128
```
129
130
[Style Validation](./validation.md)
131
132
### Style Formatting and Migration
133
134
Tools for formatting styles with proper key ordering and migrating older style versions to current specifications.
135
136
```typescript { .api }
137
function format(style: StyleSpecification, space?: number): string;
138
function migrate(style: any): StyleSpecification;
139
```
140
141
[Style Operations](./style-operations.md)
142
143
### Expression System
144
145
Powerful expression evaluation engine for data-driven styling with support for zoom-dependent and feature-dependent expressions.
146
147
```typescript { .api }
148
function createExpression(
149
expression: ExpressionSpecification,
150
propertySpec?: StylePropertySpecification
151
): {
152
result: 'success' | 'error';
153
value?: StyleExpression;
154
errors?: ParsingError[];
155
};
156
157
interface StyleExpression {
158
evaluate(
159
globals: EvaluationContext,
160
feature?: any
161
): any;
162
}
163
```
164
165
[Expression System](./expressions.md)
166
167
### Feature Filtering
168
169
Feature filtering system for creating efficient layer filters based on geometry and properties.
170
171
```typescript { .api }
172
function featureFilter(filter: FilterSpecification): FeatureFilter;
173
174
interface FeatureFilter {
175
filter: FilterExpression;
176
needGeometry: boolean;
177
needFeature: boolean;
178
}
179
```
180
181
[Feature Filtering](./feature-filtering.md)
182
183
### Color Utilities
184
185
Comprehensive color manipulation and conversion utilities supporting multiple color formats and operations.
186
187
```typescript { .api }
188
class Color {
189
constructor(r: number, g: number, b: number, a?: number);
190
static parse(input: string): Color | undefined;
191
toString(): string;
192
clone(): Color;
193
194
static readonly black: Color;
195
static readonly white: Color;
196
static readonly transparent: Color;
197
static readonly red: Color;
198
static readonly blue: Color;
199
}
200
```
201
202
[Color Utilities](./color-utilities.md)
203
204
### CLI Tools
205
206
Command-line utilities for batch processing, validation, formatting, and migration of style files.
207
208
Available commands:
209
- `gl-style-validate` - Validate style files
210
- `gl-style-format` - Format and prettify styles
211
- `gl-style-migrate` - Migrate older style versions
212
- `gl-style-composite` - Composite multiple sources
213
214
[CLI Tools](./cli-tools.md)
215
216
### Style Manipulation Utilities
217
218
Advanced utilities for style diffing, composition, layer dereferencing, and traversal operations.
219
220
```typescript { .api }
221
function diff(before: StyleSpecification, after: StyleSpecification): Command[];
222
function composite(style: StyleSpecification): StyleSpecification;
223
function derefLayers(layers: LayerSpecification[]): LayerSpecification[];
224
225
interface VisitAPI {
226
eachSource(style: StyleSpecification, callback: (source: SourceSpecification) => void): void;
227
eachLayer(style: StyleSpecification, callback: (layer: LayerSpecification) => void): void;
228
eachProperty(
229
style: StyleSpecification,
230
options: { paint?: boolean; layout?: boolean },
231
callback: PropertyCallback
232
): void;
233
}
234
235
const visit: VisitAPI;
236
```
237
238
[Style Manipulation](./style-manipulation.md)
239
240
### Legacy Function Support
241
242
Legacy function utilities for working with pre-expression function specifications.
243
244
```typescript { .api }
245
interface StyleFunctionAPI {
246
createFunction(parameters: any, propertySpec: StylePropertySpecification): any;
247
isFunction(value: any): boolean;
248
convertFunction(parameters: any, propertySpec: StylePropertySpecification): any;
249
}
250
251
const function: StyleFunctionAPI;
252
function convertFilter(filter: any): FilterSpecification;
253
function validateMapboxApiSupported(
254
style: StyleSpecification,
255
sourceAccessToken?: string
256
): ValidationError[];
257
```
258
259
## Types
260
261
Core type definitions used throughout the API:
262
263
```typescript { .api }
264
interface StyleSpecification {
265
version: 8;
266
name?: string;
267
metadata?: unknown;
268
sources: {[_: string]: SourceSpecification};
269
layers: LayerSpecification[];
270
sprite?: string;
271
glyphs?: string;
272
transition?: TransitionSpecification;
273
light?: LightSpecification;
274
lights?: LightsSpecification;
275
terrain?: TerrainSpecification;
276
fog?: FogSpecification;
277
projection?: ProjectionSpecification;
278
imports?: ImportSpecification[];
279
}
280
281
type LayerSpecification =
282
| FillLayerSpecification
283
| LineLayerSpecification
284
| SymbolLayerSpecification
285
| CircleLayerSpecification
286
| HeatmapLayerSpecification
287
| FillExtrusionLayerSpecification
288
| RasterLayerSpecification
289
| HillshadeLayerSpecification
290
| BackgroundLayerSpecification
291
| SkyLayerSpecification
292
| ModelLayerSpecification;
293
294
type SourceSpecification =
295
| VectorSourceSpecification
296
| RasterSourceSpecification
297
| RasterDEMSourceSpecification
298
| GeoJSONSourceSpecification
299
| ImageSourceSpecification
300
| VideoSourceSpecification;
301
```