Understanding the .geolibre.json Project Schema in GeoLibre

The .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. The .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 contains standardized fields that define the project environment. According to the schema definition in 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 for creating, parsing, and manipulating project files.

Creating and Serializing Projects

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

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 files using the parseProject function:

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:

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 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, ensuring the file always reflects the current workspace state without blocking the interface.

The Python sidecar in python/src/geolibre/project.py mirrors this schema for Jupyter integration:

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 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) and Python (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 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 and 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) as the single source of truth during editing sessions. All UI interactions modify this store, which automatically persists changes to .geolibre.json through a debounced autosave mechanism, ensuring the file remains synchronized with the workspace without manual intervention.

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