0
# Style Validation
1

2
Comprehensive style validation system that ensures Mapbox GL styles conform to the specification. Provides detailed error reporting with line numbers and specific error messages for debugging invalid styles.
3

4
## Capabilities
5

6
### Main Validation Function
7

8
Validates a complete style object against the Mapbox GL style specification.
9

10
```typescript { .api }
11
/**
12
 * Validates a complete style object against the Mapbox GL style specification
13
 * @param style - Style object to validate
14
 * @param styleSpec - Optional style specification to validate against (defaults to latest)
15
 * @returns Array of validation errors (empty if valid)
16
 */
17
function validate(
18
  style: StyleSpecification | string | Buffer, 
19
  styleSpec?: StyleReference
20
): ValidationError[];
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { validate, latest } from "@mapbox/mapbox-gl-style-spec";
27

28
const style = {
29
  version: 8,
30
  sources: {
31
    "my-source": {
32
      type: "vector",
33
      url: "mapbox://mapbox.mapbox-streets-v8"
34
    }
35
  },
36
  layers: [
37
    {
38
      id: "background",
39
      type: "background",
40
      paint: {
41
        "background-color": "#f0f0f0"
42
      }
43
    }
44
  ]
45
};
46

47
const errors = validate(style, latest);
48
if (errors.length === 0) {
49
  console.log("Style is valid!");
50
} else {
51
  errors.forEach(error => {
52
    console.error(`Error: ${error.message}`);
53
    if (error.line) console.error(`Line: ${error.line}`);
54
  });
55
}
56
```
57

58
### Mapbox API Compatibility Validation
59

60
Validates whether a style is compatible with the Mapbox API, checking for features that may not be supported.
61

62
```typescript { .api }
63
/**
64
 * Validates Mapbox API compatibility for a style
65
 * @param style - Style object to validate
66
 * @param styleSpec - Optional style specification (defaults to latest)
67
 * @returns Array of compatibility warnings and errors
68
 */
69
function validateMapboxApiSupported(
70
  style: StyleSpecification,
71
  sourceAccessToken?: string
72
): ValidationError[];
73
```
74

75
### Individual Component Validators
76

77
Specialized validators for specific style components, useful for validating individual parts of a style during construction. These validators are also exported from the main validate function.
78

79
```typescript
80
import { 
81
  source as validateSource,
82
  layer as validateLayer,
83
  filter as validateFilter,
84
  paintProperty as validatePaintProperty,
85
  layoutProperty as validateLayoutProperty,
86
  lights as validateLights,
87
  terrain as validateTerrain,
88
  fog as validateFog,
89
  model as validateModel
90
} from "@mapbox/mapbox-gl-style-spec/validate";
91
```
92

93
```typescript { .api }
94
/**
95
 * Validates a source configuration
96
 * @param options - Validation options including the source and style context
97
 * @returns Array of validation errors
98
 */
99
function validateSource(options: {
100
  key: string;
101
  value: SourceSpecification;
102
  style: StyleSpecification;
103
  styleSpec: StyleReference;
104
}): ValidationError[];
105

106
/**
107
 * Validates a layer configuration
108
 * @param options - Validation options including the layer and style context
109
 * @returns Array of validation errors
110
 */
111
function validateLayer(options: {
112
  key: string;
113
  value: LayerSpecification;
114
  style: StyleSpecification;
115
  styleSpec: StyleReference;
116
}): ValidationError[];
117

118
/**
119
 * Validates a filter expression
120
 * @param options - Validation options including the filter
121
 * @returns Array of validation errors
122
 */
123
function validateFilter(options: {
124
  key: string;
125
  value: FilterSpecification;
126
  style: StyleSpecification;
127
  styleSpec: StyleReference;
128
}): ValidationError[];
129

130
/**
131
 * Validates a paint property for a layer
132
 * @param options - Validation options including property name, value, and layer context
133
 * @returns Array of validation errors
134
 */
135
function validatePaintProperty(options: {
136
  key: string;
137
  value: any;
138
  layer: LayerSpecification;
139
  style: StyleSpecification;
140
  styleSpec: StyleReference;
141
}): ValidationError[];
142

143
/**
144
 * Validates a layout property for a layer
145
 * @param options - Validation options including property name, value, and layer context
146
 * @returns Array of validation errors
147
 */
148
function validateLayoutProperty(options: {
149
  key: string;
150
  value: any;
151
  layer: LayerSpecification;
152
  style: StyleSpecification;
153
  styleSpec: StyleReference;
154
}): ValidationError[];
155
```
156

157
### 3D and Effects Validators
158

159
Validators for 3D features and visual effects.
160

161
```typescript { .api }
162
/**
163
 * Validates 3D lights configuration
164
 * @param options - Validation options for lights
165
 * @returns Array of validation errors
166
 */
167
function validateLights(options: {
168
  key: string;
169
  value: LightsSpecification;
170
  style: StyleSpecification;
171
  styleSpec: StyleReference;
172
}): ValidationError[];
173

174
/**
175
 * Validates terrain configuration
176
 * @param options - Validation options for terrain
177
 * @returns Array of validation errors
178
 */
179
function validateTerrain(options: {
180
  key: string;
181
  value: TerrainSpecification;
182
  style: StyleSpecification;
183
  styleSpec: StyleReference;
184
}): ValidationError[];
185

186
/**
187
 * Validates fog effects configuration
188
 * @param options - Validation options for fog
189
 * @returns Array of validation errors
190
 */
191
function validateFog(options: {
192
  key: string;
193
  value: FogSpecification;
194
  style: StyleSpecification;
195
  styleSpec: StyleReference;
196
}): ValidationError[];
197

198
/**
199
 * Validates 3D model configuration
200
 * @param options - Validation options for models
201
 * @returns Array of validation errors
202
 */
203
function validateModel(options: {
204
  key: string;
205
  value: ModelSpecification;
206
  style: StyleSpecification;
207
  styleSpec: StyleReference;
208
}): ValidationError[];
209
```
210

211
## Types
212

213
```typescript { .api }
214
class ValidationError {
215
  /** Human-readable error message */
216
  message: string;
217
  /** Optional identifier indicating the context of the error */
218
  identifier?: string | null;
219
  /** Optional line number where the error occurred */
220
  line?: number | null;
221
  
222
  constructor(
223
    key: string | null | undefined, 
224
    value: any, 
225
    message: string, 
226
    identifier?: string | null
227
  );
228
}
229

230
class ValidationWarning extends ValidationError {}
231

232
class ParsingError {
233
  /** Human-readable error message */
234
  message: string;
235
  /** The underlying error object */
236
  error: Error;
237
  /** Line number where parsing failed */
238
  line: number;
239
  
240
  constructor(error: Error);
241
}
242

243
interface StyleReference {
244
  version: number;
245
  [componentName: string]: any;
246
}
247
```