or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-tools.mdcolor-utilities.mdexpressions.mdfeature-filtering.mdindex.mdstyle-manipulation.mdstyle-operations.mdvalidation.md
tile.json

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

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@mapbox/mapbox-gl-style-spec@14.13.x

To install, run

npx @tessl/cli install tessl/npm-mapbox--mapbox-gl-style-spec@14.13.0

index.mddocs/

Mapbox GL Style Specification

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.

Package Information

  • Package Name: @mapbox/mapbox-gl-style-spec
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @mapbox/mapbox-gl-style-spec

Core Imports

import { 
  validate, 
  format, 
  migrate, 
  expression, 
  featureFilter,
  Color,
  latest,
  v8,
  diff,
  composite,
  derefLayers,
  visit,
  function as styleFunction,
  convertFilter,
  ValidationError,
  ParsingError,
  validateMapboxApiSupported
} from "@mapbox/mapbox-gl-style-spec";

For CommonJS:

const { 
  validate, 
  format, 
  migrate, 
  expression, 
  featureFilter,
  Color,
  latest,
  v8,
  diff,
  composite,
  derefLayers,
  visit,
  function: styleFunction,
  convertFilter,
  ValidationError,
  ParsingError,
  validateMapboxApiSupported
} = require("@mapbox/mapbox-gl-style-spec");

Basic Usage

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

// Validate a style
const styleObject = {
  version: 8,
  sources: {},
  layers: []
};

const errors = validate(styleObject, latest);
if (errors.length === 0) {
  console.log("Style is valid!");
} else {
  console.error("Validation errors:", errors);
}

// Format a style with proper indentation
const formatted = format(styleObject, 2);

// Migrate an older style to current version
const migratedStyle = migrate(oldStyleObject);

Architecture

The Mapbox GL Style Specification package is built around several key systems:

  • Validation System: Comprehensive style specification compliance checking with detailed error reporting
  • Expression Engine: Data-driven styling computation with zoom and feature-based expressions
  • Style Manipulation: Tools for formatting, migration, diffing, and composition of styles
  • Feature Filtering: Geometric and property-based filtering for map layers
  • Type System: Complete TypeScript definitions for all style specification components
  • CLI Tools: Command-line utilities for batch processing and automation workflows

Capabilities

Style Validation

Core validation functionality ensuring styles conform to the Mapbox GL specification. Provides detailed error reporting for debugging invalid styles.

function validate(
  style: StyleSpecification | string | Buffer, 
  styleSpec?: StyleReference
): ValidationError[];

class ValidationError {
  message: string;
  identifier?: string | null;
  line?: number | null;
  constructor(
    key: string | null | undefined, 
    value: any, 
    message: string, 
    identifier?: string | null
  );
}

class ValidationWarning extends ValidationError {}

class ParsingError {
  message: string;
  error: Error;
  line: number;
  constructor(error: Error);
}

Style Validation

Style Formatting and Migration

Tools for formatting styles with proper key ordering and migrating older style versions to current specifications.

function format(style: StyleSpecification, space?: number): string;
function migrate(style: any): StyleSpecification;

Style Operations

Expression System

Powerful expression evaluation engine for data-driven styling with support for zoom-dependent and feature-dependent expressions.

function createExpression(
  expression: ExpressionSpecification, 
  propertySpec?: StylePropertySpecification
): {
  result: 'success' | 'error';
  value?: StyleExpression;
  errors?: ParsingError[];
};

interface StyleExpression {
  evaluate(
    globals: EvaluationContext, 
    feature?: any
  ): any;
}

Expression System

Feature Filtering

Feature filtering system for creating efficient layer filters based on geometry and properties.

function featureFilter(filter: FilterSpecification): FeatureFilter;

interface FeatureFilter {
  filter: FilterExpression;
  needGeometry: boolean;
  needFeature: boolean;
}

Feature Filtering

Color Utilities

Comprehensive color manipulation and conversion utilities supporting multiple color formats and operations.

class Color {
  constructor(r: number, g: number, b: number, a?: number);
  static parse(input: string): Color | undefined;
  toString(): string;
  clone(): Color;
  
  static readonly black: Color;
  static readonly white: Color;
  static readonly transparent: Color;
  static readonly red: Color;
  static readonly blue: Color;
}

Color Utilities

CLI Tools

Command-line utilities for batch processing, validation, formatting, and migration of style files.

Available commands:

  • gl-style-validate - Validate style files
  • gl-style-format - Format and prettify styles
  • gl-style-migrate - Migrate older style versions
  • gl-style-composite - Composite multiple sources

CLI Tools

Style Manipulation Utilities

Advanced utilities for style diffing, composition, layer dereferencing, and traversal operations.

function diff(before: StyleSpecification, after: StyleSpecification): Command[];
function composite(style: StyleSpecification): StyleSpecification;
function derefLayers(layers: LayerSpecification[]): LayerSpecification[];

interface VisitAPI {
  eachSource(style: StyleSpecification, callback: (source: SourceSpecification) => void): void;
  eachLayer(style: StyleSpecification, callback: (layer: LayerSpecification) => void): void;
  eachProperty(
    style: StyleSpecification,
    options: { paint?: boolean; layout?: boolean },
    callback: PropertyCallback
  ): void;
}

const visit: VisitAPI;

Style Manipulation

Legacy Function Support

Legacy function utilities for working with pre-expression function specifications.

interface StyleFunctionAPI {
  createFunction(parameters: any, propertySpec: StylePropertySpecification): any;
  isFunction(value: any): boolean;
  convertFunction(parameters: any, propertySpec: StylePropertySpecification): any;
}

const function: StyleFunctionAPI;
function convertFilter(filter: any): FilterSpecification;
function validateMapboxApiSupported(
  style: StyleSpecification,
  sourceAccessToken?: string
): ValidationError[];

Types

Core type definitions used throughout the API:

interface StyleSpecification {
  version: 8;
  name?: string;
  metadata?: unknown;
  sources: {[_: string]: SourceSpecification};
  layers: LayerSpecification[];
  sprite?: string;
  glyphs?: string;
  transition?: TransitionSpecification;
  light?: LightSpecification;
  lights?: LightsSpecification;
  terrain?: TerrainSpecification;
  fog?: FogSpecification;
  projection?: ProjectionSpecification;
  imports?: ImportSpecification[];
}

type LayerSpecification = 
  | FillLayerSpecification 
  | LineLayerSpecification 
  | SymbolLayerSpecification 
  | CircleLayerSpecification
  | HeatmapLayerSpecification
  | FillExtrusionLayerSpecification
  | RasterLayerSpecification
  | HillshadeLayerSpecification
  | BackgroundLayerSpecification
  | SkyLayerSpecification
  | ModelLayerSpecification;

type SourceSpecification = 
  | VectorSourceSpecification 
  | RasterSourceSpecification 
  | RasterDEMSourceSpecification
  | GeoJSONSourceSpecification 
  | ImageSourceSpecification 
  | VideoSourceSpecification;