Data Formats and Parsing

This document describes the data format and parsing subsystem in OpenLayers, which enables reading and writing geographic data in various geospatial standards including GeoJSON, KML, WFS, MVT, and others. The format classes provide readers and writers that convert between external format representations and OpenLayers features, with comprehensive XML processing utilities supporting the XML-based formats. For information about vector data structures themselves, see Spatial Data and Utilities.

Format System Overview

The format system in OpenLayers provides a unified approach to reading and writing geospatial data in different formats. All format classes follow a consistent API pattern while handling the specifics of each format's encoding and decoding logic.

Format Class Hierarchy

The format system is organized around a class hierarchy that provides shared functionality while enabling format-specific implementations.

100%

Core Concepts

FeatureFormat

The FeatureFormat class is the base class for all format implementations. It defines the API for reading and writing geographic data.

Key concepts provided by the base class:

• dataProjection: The projection of the data (as read from or written to the source)
• featureProjection: The projection of features as they're used in OpenLayers
• Read/Write Options: Controls projection transformations, filtering, and other format-specific behaviors
• Feature Class: Determines the type of feature objects to create (Feature or RenderFeature)

Reading and Writing Flow

The format system follows a common pattern for reading and writing data:

100%

Reading Geographic Data

All format classes implement methods to read features, geometries, and projections from various sources:

• readFeature(source, options): Reads a single feature from a source
• readFeatures(source, options): Reads multiple features from a source
• readGeometry(source, options): Reads a geometry from a source
• readProjection(source): Reads the projection information from a source

Each format implements specific parsing logic while maintaining a consistent API. The format-specific implementations typically handle:

1. Parsing the source data based on format specifications
2. Creating appropriate geometries (Point, LineString, Polygon, etc.)
3. Setting feature properties from source attributes
4. Handling projection transformations when needed

Coordinate Transformation

When reading geographic data, coordinates are often transformed between different coordinate reference systems. This is handled by the transformGeometryWithOptions and transformExtentWithOptions functions:

100%

Writing Geographic Data

Format classes also provide methods to write features and geometries to various formats:

• writeFeature(feature, options): Writes a single feature
• writeFeatures(features, options): Writes multiple features
• writeGeometry(geometry, options): Writes a geometry

Writing typically involves:

1. Transforming geometries to the target projection if needed
2. Serializing the geometry according to the format specification
3. Adding feature properties to the output
4. Formatting according to the format's syntax rules

XML Processing Utilities

OpenLayers provides comprehensive XML processing utilities in xml.js that support all XML-based format implementations. These utilities handle XML parsing, serialization, and namespace management.

Core XML Processing Functions

XML Processing Infrastructure

100%

Key XML Utility Functions:

Function	Purpose	Location
parse(xml)	Parse XML string to Document	src/ol/xml.js96-103
parseNode(parsersNS, node, objectStack)	Parse XML node with namespace-aware parsers	src/ol/xml.js388-406
pushParseAndPop(object, parsersNS, node, objectStack)	Parse node and manage object stack	src/ol/xml.js409-423
makeStructureNS(namespaceURIs, structure)	Create namespace-aware parser structure	src/ol/xml.js369-385
makeArrayPusher(valueReader)	Create parser that pushes values to array	src/ol/xml.js132-157
serialize(serializersNS, nodeFactory, values, objectStack)	Serialize values to XML nodes	src/ol/xml.js426-476

Format Types

OpenLayers provides a wide range of format implementations categorized by their underlying format structure.

XML-Based Formats

XML-based formats parse and generate XML documents using the XML processing utilities described above.

Major XML Format Implementations

Format	Class	Description	Importance
KML	KML	Keyhole Markup Language with style support	High (83.87)
WFS	WFS	Web Feature Service transactions and queries	High (54.75)
GML	GMLBase, GML2, GML3, GML32	Geography Markup Language family	Medium (37.74)
GPX	GPX	GPS Exchange Format	Medium (25.38)
OSMXML	OSMXML	OpenStreetMap XML	Low (15.21)
WMSGetFeatureInfo	WMSGetFeatureInfo	WMS GetFeatureInfo results	Low (13.78)

XML Format Parser Structure Example (KML)

JSON-Based Formats

JSON-based formats parse and generate JSON objects. They handle JSON parsing and serialization.

Major JSON Format Implementations

Format	Class	Description	Importance
MVT	MVT	Mapbox Vector Tiles (Protocol Buffers)	High (41.08)
GeoJSON	GeoJSON	OGC GeoJSON standard	Medium (30.82)
EsriJSON	EsriJSON	Esri JSON format	Medium (24.20)
TopoJSON	TopoJSON	Topological JSON	Low (20.30)

MVT Format Processing (Binary Protocol Buffers)

100%

Text-Based Formats

Text-based formats handle parsing and generating plain text formats.

Text Format Implementations

Format	Class	Description	Importance
Polyline	Polyline	Encoded Polyline Algorithm	Medium (31.15)
WKT	WKT	Well-Known Text geometry representation	Medium (23.78)
IGC	IGC	International Gliding Commission flight format	Low (18.73)

Text Format Parsing Pipeline

100%

Format-Specific Features

Each format implementation has specific features and behaviors based on the format's specification.

Example: KML Format Implementation

The KML class is one of the most comprehensive format implementations, handling Keyhole Markup Language files with full style support and advanced features:

KML Format Class Structure

100%

KML Advanced Features:

• Style Management: Shared styles, style maps, and inline styles via sharedStyles_ and createFeatureStyleFunction
• Geometry Support: All geometry types including Google Earth extensions (gx:Track, gx:MultiTrack)
• Metadata Extraction: Names, descriptions, network links, regions, and camera information
• Icon Handling: Custom icon URL transformation via iconUrlFunction_
• Coordinate Reading: readFlatCoordinates(node) with flexible coordinate parsing

Example: WFS Format Implementation

The WFS class handles Web Feature Service transactions and queries, representing one of the most complex XML format implementations:

WFS Format Architecture

100%

WFS Implementation Details:

• Multi-version Support: Supports WFS versions 1.0.0, 1.1.0, and 2.0.0 with different GML format backends
• Transaction Support: Full CRUD operations via writeTransaction with Insert, Update, Delete operations
• Query Building: Complex query construction with BBOX filters, property names, and custom filters
• Namespace Management: Flexible feature namespace configuration for multi-schema support
• Response Parsing: Transaction responses, feature collection metadata, and projection detection

Working with Formats

Common Usage Patterns

Formats are typically used in the following ways:

1. Reading Features from a Source:

   // Create a format instance
   const format = new ol.format.GeoJSON();
   
   // Read features from a source
   const features = format.readFeatures(source, {
     dataProjection: 'EPSG:4326',
     featureProjection: 'EPSG:3857'
   });

2. Writing Features to a Format:

   // Create a format instance
   const format = new ol.format.GeoJSON();
   
   // Write features to GeoJSON
   const geojson = format.writeFeatures(features, {
     dataProjection: 'EPSG:4326',
     featureProjection: 'EPSG:3857'
   });

Format Options

Most format classes accept options that control their behavior:

Option	Description	Examples
dataProjection	Projection of the data source	'EPSG:4326', 'EPSG:3857'
featureProjection	Projection for features in OpenLayers	'EPSG:3857', 'EPSG:4326'
geometryName	Name of the geometry property	'geometry', 'the_geom'
extractStyles	Whether to extract styles (for KML, etc.)	true, false
featureClass	Class used for features	ol.Feature, ol.render.Feature

Advanced Topics

Projection Handling

Formats handle coordinate system transformations through the transformGeometryWithOptions and transformExtentWithOptions functions. These functions:

1. Compare the data projection and feature projection
2. If they differ, transform the coordinates
3. Apply any additional transformations (e.g., rounding coordinates)

// Reading features with projection transformation
const features = format.readFeatures(source, {
  dataProjection: 'EPSG:4326',    // Source data is in WGS 84
  featureProjection: 'EPSG:3857'  // Features will be in Web Mercator
});

RenderFeature vs Feature

The format system can create two types of features:

1. Feature: Full-featured object with geometry and properties that can be modified
2. RenderFeature: Lightweight, optimized for rendering, cannot be modified after creation

The choice affects performance vs. flexibility:

// Using RenderFeature for better rendering performance
const format = new ol.format.GeoJSON({
  featureClass: ol.render.Feature
});

Extending Formats

Creating custom formats involves extending one of the base classes and implementing parsing and serializing logic:

1. Extend a base class (XMLFeature, JSONFeature, or TextFeature)
2. Implement the required read/write methods
3. Handle format-specific parsing and serialization

Conclusion

The format system in OpenLayers provides a comprehensive set of tools for reading and writing geographic data in various formats. With a consistent API across all formats and robust support for coordinate transformations, it enables seamless interoperability with different data sources and services.