tessl/npm-mapbox--mapbox-gl-style-spec

Specification and utilities for working with Mapbox GL styles including validation, migration, formatting, and expression evaluation

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Style Validation

Name: tessl/npm-mapbox--mapbox-gl-style-spec
Author: tessl

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.

Capabilities

Main Validation Function

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

/**
 * Validates a complete style object against the Mapbox GL style specification
 * @param style - Style object to validate
 * @param styleSpec - Optional style specification to validate against (defaults to latest)
 * @returns Array of validation errors (empty if valid)
 */
function validate(
  style: StyleSpecification | string | Buffer, 
  styleSpec?: StyleReference
): ValidationError[];

Usage Examples:

import { validate, latest } from "@mapbox/mapbox-gl-style-spec";

const style = {
  version: 8,
  sources: {
    "my-source": {
      type: "vector",
      url: "mapbox://mapbox.mapbox-streets-v8"
    }
  },
  layers: [
    {
      id: "background",
      type: "background",
      paint: {
        "background-color": "#f0f0f0"
      }
    }
  ]
};

const errors = validate(style, latest);
if (errors.length === 0) {
  console.log("Style is valid!");
} else {
  errors.forEach(error => {
    console.error(`Error: ${error.message}`);
    if (error.line) console.error(`Line: ${error.line}`);
  });
}

Mapbox API Compatibility Validation

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

/**
 * Validates Mapbox API compatibility for a style
 * @param style - Style object to validate
 * @param styleSpec - Optional style specification (defaults to latest)
 * @returns Array of compatibility warnings and errors
 */
function validateMapboxApiSupported(
  style: StyleSpecification,
  sourceAccessToken?: string
): ValidationError[];

Individual Component Validators

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.

import { 
  source as validateSource,
  layer as validateLayer,
  filter as validateFilter,
  paintProperty as validatePaintProperty,
  layoutProperty as validateLayoutProperty,
  lights as validateLights,
  terrain as validateTerrain,
  fog as validateFog,
  model as validateModel
} from "@mapbox/mapbox-gl-style-spec/validate";

/**
 * Validates a source configuration
 * @param options - Validation options including the source and style context
 * @returns Array of validation errors
 */
function validateSource(options: {
  key: string;
  value: SourceSpecification;
  style: StyleSpecification;
  styleSpec: StyleReference;
}): ValidationError[];

/**
 * Validates a layer configuration
 * @param options - Validation options including the layer and style context
 * @returns Array of validation errors
 */
function validateLayer(options: {
  key: string;
  value: LayerSpecification;
  style: StyleSpecification;
  styleSpec: StyleReference;
}): ValidationError[];

/**
 * Validates a filter expression
 * @param options - Validation options including the filter
 * @returns Array of validation errors
 */
function validateFilter(options: {
  key: string;
  value: FilterSpecification;
  style: StyleSpecification;
  styleSpec: StyleReference;
}): ValidationError[];

/**
 * Validates a paint property for a layer
 * @param options - Validation options including property name, value, and layer context
 * @returns Array of validation errors
 */
function validatePaintProperty(options: {
  key: string;
  value: any;
  layer: LayerSpecification;
  style: StyleSpecification;
  styleSpec: StyleReference;
}): ValidationError[];

/**
 * Validates a layout property for a layer
 * @param options - Validation options including property name, value, and layer context
 * @returns Array of validation errors
 */
function validateLayoutProperty(options: {
  key: string;
  value: any;
  layer: LayerSpecification;
  style: StyleSpecification;
  styleSpec: StyleReference;
}): ValidationError[];

3D and Effects Validators

Validators for 3D features and visual effects.

/**
 * Validates 3D lights configuration
 * @param options - Validation options for lights
 * @returns Array of validation errors
 */
function validateLights(options: {
  key: string;
  value: LightsSpecification;
  style: StyleSpecification;
  styleSpec: StyleReference;
}): ValidationError[];

/**
 * Validates terrain configuration
 * @param options - Validation options for terrain
 * @returns Array of validation errors
 */
function validateTerrain(options: {
  key: string;
  value: TerrainSpecification;
  style: StyleSpecification;
  styleSpec: StyleReference;
}): ValidationError[];

/**
 * Validates fog effects configuration
 * @param options - Validation options for fog
 * @returns Array of validation errors
 */
function validateFog(options: {
  key: string;
  value: FogSpecification;
  style: StyleSpecification;
  styleSpec: StyleReference;
}): ValidationError[];

/**
 * Validates 3D model configuration
 * @param options - Validation options for models
 * @returns Array of validation errors
 */
function validateModel(options: {
  key: string;
  value: ModelSpecification;
  style: StyleSpecification;
  styleSpec: StyleReference;
}): ValidationError[];

Types

class ValidationError {
  /** Human-readable error message */
  message: string;
  /** Optional identifier indicating the context of the error */
  identifier?: string | null;
  /** Optional line number where the error occurred */
  line?: number | null;
  
  constructor(
    key: string | null | undefined, 
    value: any, 
    message: string, 
    identifier?: string | null
  );
}

class ValidationWarning extends ValidationError {}

class ParsingError {
  /** Human-readable error message */
  message: string;
  /** The underlying error object */
  error: Error;
  /** Line number where parsing failed */
  line: number;
  
  constructor(error: Error);
}

interface StyleReference {
  version: number;
  [componentName: string]: any;
}