# GeoLibre `.geolibre.json` Project Format Schema: Complete Technical Reference

> Explore the .geolibre.json project format schema, the single source of truth for GeoLibre workspaces. Understand how it serializes application state, basemaps, layers, and more using JSON.

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

---

**The [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) file serves as the single source of truth for GeoLibre workspaces, serializing the complete application state—including map view, basemaps, layers, plugin data, and environment variables—into a JSON format aligned with the MapLibre GL style specification.**

GeoLibre is an open-source geospatial mapping platform that uses a structured JSON format to persist project states. The [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) project format schema defines how every aspect of a mapping workspace, from camera positions to custom plugin configurations, gets stored and shared. Understanding this schema is essential for developers extending GeoLibre or integrating external data pipelines.

## Core Schema Structure

The [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) schema is deliberately aligned with the MapLibre GL style specification, allowing valid MapLibre styles to embed directly while adding GeoLibre-specific wrappers for state management.

### Top-Level Properties

According to [`docs/project-format.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/project-format.md), the root object contains these fields:

- **`version`** – Project schema version (e.g., `"1.0"`) used for forward-compatibility checks.
- **`title`** / **`description`** – Human-readable metadata displayed in the UI.
- **`basemap`** – Basemap definition containing `id`, `url`, `type`, and `attribution`, mirroring the MapLibre basemap specification.
- **`view`** – Current camera state with `center` (longitude/latitude array), `zoom`, `pitch`, and `bearing`, restored automatically on project load.
- **`styleLibrary`** – Optional array of reusable style objects referenceable by layers.
- **`plugins`** – Object keyed by plugin ID, where each entry stores persisted state for that extension (e.g., remote-file-browser UI or AI-assistant settings).
- **`environment`** – Plain-text key/value pairs for API keys and runtime variables. **Note:** These values are not encrypted; avoid committing sensitive credentials to public repositories.
- **`photo`** – Serialized configuration for the "Take Photo" tool.
- **`storymap`** – Optional story-map configuration including chapters, narrative text, and layout definitions.
- **`settings`** – UI-level preferences such as theme, language, and map control toggles.
- **`metadata`** – Miscellaneous tracking info including `createdAt` and `lastModified` timestamps.

### Layer Specifications

As defined in [`packages/core/src/types.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/types.ts), the `layers` property contains an array of layer objects extending the MapLibre GL style spec with GeoLibre-specific fields:

- **`id`** – Unique identifier for the layer.
- **`type`** – Layer type enumeration including `raster`, `vector`, `geojson`, and `custom`.
- **`source`** – Data reference supporting inline GeoJSON, remote URLs, or DuckDB-WASM references.
- **`layout`** / **`paint`** – Standard MapLibre style rules defining visual appearance.
- **`metadata`** – Plugin-specific state storage for custom layer behaviors.

## Working with Project Files

### Loading and Saving Projects

The `loadProject` function from `@geolibre/core` handles deserialization, while the Zustand store in [`packages/core/src/store.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts) manages autosave functionality.

Load a project from a public URL:

```typescript
import { loadProject } from '@geolibre/core';

const url = 'https://share.geolibre.app/user/my-map.geolibre.json';
loadProject({ url });

```

Trigger manual saves (normally autosaved after 3 seconds of inactivity):

```typescript
import { useAppStore } from '@geolibre/core';

await useAppStore.getState().saveProject('/tmp/my-project.geolibre.json');

```

### Programmatic Layer Manipulation

Access the store directly to modify layers programmatically:

```typescript
import { useAppStore } from '@geolibre/core';

// Add a new GeoJSON layer with custom styling
useAppStore.getState().addGeoJsonLayer({
  id: 'countries',
  data: myGeoJson,
  paint: { 'fill-color': '#ffcc00' },
});

```

### Python Integration

The Python sidecar in [`python/src/geolibre/project.py`](https://github.com/opengeos/GeoLibre/blob/main/python/src/geolibre/project.py) provides helpers for building and validating projects in Jupyter environments:

```python
from geolibre import GeoLibre

m = GeoLibre()
m.load_project('my-map.geolibre.json')

# Access environment variables stored in the project

api_key = m.project['environment']['MY_API_KEY']

```

## Implementation and Source References

The schema implementation spans multiple packages:

- **[`docs/project-format.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/project-format.md)** – Human-readable reference documenting the complete JSON schema.
- **[`packages/core/src/types.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/types.ts)** – TypeScript definitions for `Project`, `Layer`, and related interfaces that drive JSON validation.
- **[`python/src/geolibre/project.py`](https://github.com/opengeos/GeoLibre/blob/main/python/src/geolibre/project.py)** – Python utilities for serializing and validating project dictionaries.
- **[`packages/core/src/store.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts)** – Zustand store managing live project state and autosave synchronization to [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json).
- **[`apps/geolibre-desktop/src/hooks/usePlugins.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/hooks/usePlugins.ts)** – Hook registering plugin state persistence into the project file structure.

## Summary

- The [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) schema captures complete GeoLibre workspace state in a single JSON file.
- Top-level properties include `version`, `basemap`, `view`, `layers`, `plugins`, and `environment`.
- Layer objects follow the MapLibre GL style specification with additional `metadata` fields for plugin state.
- The TypeScript core exposes `loadProject` and `useAppStore` for file operations, while the Python package provides Jupyter integration via [`python/src/geolibre/project.py`](https://github.com/opengeos/GeoLibre/blob/main/python/src/geolibre/project.py).
- Environment variables stored in the `environment` object are plaintext and require careful handling to avoid exposing secrets.

## Frequently Asked Questions

### What is the [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) file used for?

The [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) file stores the complete serialized state of a GeoLibre project, enabling users to save, share, and reopen exact workspace configurations including map views, layer styles, and plugin settings.

### Is the [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) format compatible with MapLibre styles?

Yes, the schema is intentionally aligned with the MapLibre GL style specification. Any valid MapLibre style can embed directly into the `layers` or `styleLibrary` properties, while GeoLibre adds wrapper fields for application state like `plugins` and `environment`.

### How are sensitive credentials handled in [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json)?

The `environment` property stores API keys and secrets as plain-text key/value pairs. These values are **not encrypted** in the project file, so you should avoid committing [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) files containing sensitive data to public version control repositories.

### Can I programmatically modify [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) files outside the GeoLibre UI?

Yes, you can manipulate these files using the Python package via [`python/src/geolibre/project.py`](https://github.com/opengeos/GeoLibre/blob/main/python/src/geolibre/project.py) or directly edit the JSON, provided you maintain schema validity as defined in [`packages/core/src/types.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/types.ts). The TypeScript store in [`packages/core/src/store.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts) also exposes methods like `saveProject` for programmatic updates from within the application runtime.