# Understanding the .geolibre.json Project Schema in GeoLibre

> Explore the .geolibre.json project schema. Learn how this GeoLibre file defines your entire workspace state for easy restoration and sharing.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: api-reference
- Published: 2026-08-05

---

**The [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) file is a single JSON document that captures the complete GeoLibre workspace state, including map view configuration, data layers, visual styles, plugin settings, and dashboard layouts, enabling full project restoration and portable sharing.**

GeoLibre stores an entire geospatial workspace in a single JSON file following a well-defined schema documented in [`docs/project-format.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/project-format.md). The [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) project schema serves as the definitive specification for serializing application state, ensuring that every aspect of the map—camera positions, data sources, styling rules, and UI configurations—can be saved, transferred, and restored with complete fidelity.

## Core Schema Structure

The root object of [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) contains standardized fields that define the project environment. According to the schema definition in [`packages/core/src/types.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/types.ts), the file structure includes:

- **`version`** – Schema version string (e.g., `"0.1.0"`)
- **`name`** – Human-readable project title
- **`mapView`** – Camera state object containing `center`, `zoom`, `bearing`, `pitch`, and optional `bbox`
- **`basemapStyleUrl`** – URL of the MapLibre style used as the basemap (empty string for blank backgrounds)
- **`basemapVisible`** – Boolean flag showing or hiding the background layer
- **`basemapOpacity`** – Numeric opacity value between 0 and 1
- **`layers`** – Array of layer objects defining data sources, visibility, and rendering parameters
- **`styles`** – Object mapping layer IDs to `LayerStyle` definitions (fills, strokes, raster adjustments)
- **`metadata`** – Free-form key/value store for custom project attributes

## Layer Architecture and Data Sources

Each entry in the `layers` array contains a complete self-description of a dataset and its presentation. As implemented in the core types, layer objects encapsulate:

- **Source definitions** – GeoJSON objects, vector tile URLs, raster tile endpoints, or remote file references
- **Visual styling** – References to the `styles` object that define fill colors, line widths, stroke properties, and raster adjustments
- **Attribute joins** – Enrichment relationships that link layer attributes to external datasets or other layers
- **Operational metadata** – Configuration for auto-refresh intervals, file-watch flags, and layer-specific custom properties

This separation between `layers` (data and visibility state) and `styles` (visualization rules) enables non-destructive style updates while preserving data source connections.

## Plugin, Widget, and Storymap State

The schema extends beyond map layers to capture the complete UI configuration:

- **`plugins`** – Object describing external plugin manifests, active plugin IDs, UI control positions, and plugin-specific settings
- **`widgets`** – Array of dashboard widgets that bind charts and statistics to layer attributes
- **`dashboardColumns`** – Integer defining the widget grid width (defaults to 2)
- **`storymap`** – Scroll-driven narrative definition including chapters, camera animations, and UI themes
- **`legend`** – Customizations for printable legends including title, layer ordering, and per-item overrides
- **`styleLibrary`** – Project-scoped collection of named, tagged style presets for reuse across layers

## Working with .geolibre.json Programmatically

The `@geolibre/core` package exposes utility functions in [`packages/core/src/index.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/index.ts) for creating, parsing, and manipulating project files.

### Creating and Serializing Projects

Initialize a skeleton project, add layers, and serialize to JSON:

```typescript
import {
  createEmptyProject,
  serializeProject,
} from "@geolibre/core";

const project = createEmptyProject({
  name: "My First GeoLibre Project",
});

project.layers.push({
  id: "roads",
  name: "Road Network",
  type: "geojson",
  source: { type: "geojson" },
  visible: true,
  opacity: 1,
  style: {
    lineColor: "#ff6600",
    lineWidth: 2,
    lineWidthUnit: "pixels",
  },
  geojson: { type: "FeatureCollection", features: [] },
});

const jsonString = serializeProject(project);

```

### Loading and Parsing Existing Projects

Read and parse existing [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) files using the `parseProject` function:

```typescript
import { readFileSync } from "fs";
import { parseProject } from "@geolibre/core";

const raw = readFileSync("my-map.geolibre.json", "utf-8");
const project = parseProject(JSON.parse(raw));

console.log(project.mapView.center);

```

### Security and Credential Redaction

Before sharing projects that may contain API keys in data source URLs, sanitize the file:

```typescript
import { redactCredentials } from "@geolibre/core";

const safeProject = redactCredentials(project);
const safeJson = JSON.stringify(safeProject, null, 2);

```

## Runtime State Management and Persistence

At runtime, GeoLibre uses a Zustand store implemented in [`packages/core/src/store.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts) as the single source of truth. When a project opens, the store initializes from the parsed JSON and maintains state through all UI interactions. A debounced autosave mechanism writes modifications back to [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json), ensuring the file always reflects the current workspace state without blocking the interface.

The Python sidecar in [`python/src/geolibre/project.py`](https://github.com/opengeos/GeoLibre/blob/main/python/src/geolibre/project.py) mirrors this schema for Jupyter integration:

```python
from geolibre import GeoLibre

m = GeoLibre()
m.add_geojson_layer(name="Cities", data=my_geojson)
m.save_project("my-cities.geolibre.json")

```

## Summary

- The [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) file completely defines a GeoLibre workspace, storing map view parameters, data layers, visual styles, plugin configurations, and dashboard layouts in a single JSON document.
- The schema separates data sources (`layers`) from presentation rules (`styles`), supporting complex attribute joins and operational metadata.
- Core API functions `createEmptyProject`, `parseProject`, `serializeProject`, and `redactCredentials` enable programmatic project management and safe sharing.
- Runtime state is managed through a Zustand store with debounced autosave, ensuring the JSON file remains synchronized with the application state.
- The schema is implemented consistently across TypeScript ([`packages/core/src/types.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/types.ts)) and Python ([`python/src/geolibre/project.py`](https://github.com/opengeos/GeoLibre/blob/main/python/src/geolibre/project.py)) environments.

## Frequently Asked Questions

### What file format does GeoLibre use to save projects?

GeoLibre persists workspaces as a single JSON file named [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) following a versioned schema (currently `0.1.0`). This file captures the complete application state including camera position, layer definitions, styling rules, plugin configurations, and dashboard widgets, enabling full project portability between sessions and deployments.

### How do I programmatically create a valid .geolibre.json file?

Import `createEmptyProject` and `serializeProject` from `@geolibre/core` to generate the JSON structure, or use the Python `GeoLibre` class and call `save_project()`. Both methods ensure the output conforms to the schema defined in [`docs/project-format.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/project-format.md) and [`packages/core/src/types.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/types.ts).

### Does the .geolibre.json schema store API credentials?

The schema may contain sensitive tokens in data source URLs. Before sharing projects, use the `redactCredentials()` utility from `@geolibre/core` to strip authentication information while preserving the project structure and layer definitions.

### How does GeoLibre handle real-time updates to the project state?

GeoLibre maintains a Zustand store ([`packages/core/src/store.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts)) as the single source of truth during editing sessions. All UI interactions modify this store, which automatically persists changes to [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) through a debounced autosave mechanism, ensuring the file remains synchronized with the workspace without manual intervention.