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

The .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 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 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, 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, 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 manages autosave functionality.

Load a project from a public URL:

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):

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:

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 provides helpers for building and validating projects in Jupyter environments:

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 – Human-readable reference documenting the complete JSON schema.
• packages/core/src/types.ts – TypeScript definitions for Project, Layer, and related interfaces that drive JSON validation.
• python/src/geolibre/project.py – Python utilities for serializing and validating project dictionaries.
• packages/core/src/store.ts – Zustand store managing live project state and autosave synchronization to .geolibre.json.
• apps/geolibre-desktop/src/hooks/usePlugins.ts – Hook registering plugin state persistence into the project file structure.

Summary

• The .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.
• 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 file used for?

The .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 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?

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 files containing sensitive data to public version control repositories.

Can I programmatically modify .geolibre.json files outside the GeoLibre UI?

Yes, you can manipulate these files using the Python package via python/src/geolibre/project.py or directly edit the JSON, provided you maintain schema validity as defined in packages/core/src/types.ts. The TypeScript store in packages/core/src/store.ts also exposes methods like saveProject for programmatic updates from within the application runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}