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
```