Data Model Architecture

A normalized, geospatially-aware schema designed for scalability, interoperability, and real-time spatial analytics.

GeoServer's data model separates spatial geometry, attribute metadata, and version history while maintaining strict referential integrity. It is optimized for high-throughput ingestion, dynamic reprojection, and multi-tenant isolation.

Design Principles OGC-compliant, schema-evolution friendly, immutable version snapshots, and CRS-agnostic geometry storage with runtime projection. All identifiers use UUIDv4 with deterministic sorting for time-series indexing.

Core Entities

Entity	Description	Key Fields	Type
`Workspace`	Tenant/project isolation boundary	`id`, `name`, `owner`, `limits`	Container
`Dataset`	Logical collection of related layers	`id`, `workspace_id`, `source_type`	Container
`Layer`	Renderable geospatial resource	`id`, `dataset_id`, `crs`, `bounding_box`	Resource
`Feature`	Individual spatial record	`id`, `layer_id`, `geometry`, `properties`	Record
`Metadata`	Provenance, styling, access rules	`target_id`, `target_type`, `json_payload`	Extension
`Version`	Immutable snapshot for audit/rollback	`id`, `base_id`, `timestamp`, `diff_hash`	History

Relationships & Hierarchy

The model follows a strict top-down containment pattern with bidirectional foreign keys for traversal optimization.

Workspace

1:N Datasets

Dataset

1:N Layers

Layer

1:N Features

Feature

1:1 Geometry + N:M Props

Features link to a single geometry index but support polymorphic attributes via a key-value store. Metadata and Versions are soft-linked to any entity using a polymorphic target_id/target_type pair.

Spatial Data Types

Geometry is stored in standardized WKB/EWKB format with runtime serialization to GeoJSON, KML, or Shapefile. The model supports all OGC Simple Features types:

POINT / MULTIPOINT
LINESTRING / MULTILINESTRING
POLYGON / MULTIPOLYGON
GEOMETRYCOLLECTION
Z-aware and M-aware variants (Z, M, ZM)

Coordinate Reference Systems

Each Layer declares a native CRS (EPSG code). At query time, GeoServer applies dynamic reprojection using the target_crs parameter. The model caches transformation matrices for common EPSG pairs to minimize runtime overhead.

Note Mixed-CRS datasets are supported but require explicit auto_transform: true at the dataset level. Geometric validity is enforced on ingestion using the JTS Topology Suite.

Versioning & Lifecycle

Every mutation triggers a new immutable Version record. The system maintains:

Base Version: Latest production snapshot
Working Version: Staging/draft state
Archived Versions: Retained per retention policy (default: 90 days)

Branching is supported via fork_from_version. Rollbacks apply diff patches rather than full rebuilds, ensuring O(k) complexity where k is the number of changed features.

API Serialization

The data model serializes to JSON-LD for machine readability and human-friendly REST endpoints. Below is a canonical Feature representation:

// GET /api/v2/layers/{id}/features/{feature_id}
{
  "@context": "https://api.geoserver.io/v2/schema/feature",
  "id": "f7a2b8c9-4d1e-4f3a-9b2c-8e7d6f5a4b3c",
  "layer_id": "layer_9x2m4n",
  "geometry": {
    "type": "Polygon",
    "crs": "EPSG:4326",
    "coordinates": [[[-122.5, 37.8], [-122.5, 37.9], [-122.4, 37.9], [-122.4, 37.8], [-122.5, 37.8]]]
  },
  "properties": {
    "land_use": "residential",
    "population_density": 2450,
    "last_surveyed": "2024-11-02T08:30:00Z"
  },
  "_meta": {
    "version": "v3",
    "checksum": "sha256:8f14e45fceea167a5a36dedd4bea2543",
    "updated_at": "2024-12-15T14:22:10Z"
  }
}

All endpoints support ?fields= projection, ?geometry_type= filtering, and ?version= temporal queries. Pagination uses cursor-based offsets for consistent ordering across large feature sets.