Project bundle

Understand the bundle format, its contents and the rules for restoring into an empty project.

Last updated: 10 November 2026

Format and version

A project bundle is a gzip-compressed UTF-8 JSON document with the .sosogis extension. Its top-level fields are format, version, brand, exported_at, sha256 and payload.

The bundle's brand field retains a compatibility value from the older format; the displayed product name is SoSoMaps. Do not change this field to update the product name.

Canonical content is UTF-8 JSON with sorted keys, unescaped Unicode characters and comma/colon separators. The reader checks format, version, digest and required array/count matches. SHA-256 checks integrity; it is not a signature that authenticates the source.

Contents

The bundle carries project name, description and settings, reference layers, active map features, equipment, connections, placement/route relationships, address and building planning records, unit-import metadata, allocation records, technical circuits and optical records.

Version 18 also includes CAD definitions, import metadata, data-source families and accepted source-row baselines. ONT and OLT uplink ports, primary/backup circuit paths and field-attachment records added in earlier formats are retained. Cable ends and equipment/connection references retain their structured relationships. Feature location quality and source information are included. Fields reserved for electric data in the bundle schema do not mean the electric module is generally available; it is Coming soon.

Users, sessions, project memberships, design/approval and work-package workflows, offline field packages, webhook subscriptions, access keys and previous change history are excluded. Raw import files, optical measurement files and photo/document attachment contents are also excluded. Field-attachment targets and metadata are retained; if the target file store lacks the content, the attachment is marked as missing. Measurement attachments are marked as unavailable on restore; parsed SOR metadata is retained. A .sosogis bundle therefore does not replace a full system backup.

Downloading a bundle

GET /api/p/{pid}/export?fmt=bundle

The bundle is generated from a consistent database snapshot. Geographic and feature-type filters do not create a partial bundle. Inconsistent internal references may return 409.

If a disabled module contains data and the user cannot read it, the bundle is refused with 403. With sufficient permission, disabled-module data is included too.

Restoring into an empty project

1. Create an empty target project in an organisation you can access.
2. Check that the modules required by the bundle are enabled in the target project.
3. Send the file in the multipart file field to POST /api/p/{pid}/bundle?ayarlar=paket.
4. Review counts, settings_conflicts and any uyarilar in the response.
5. Reread the target project; do not reuse old identifiers as identifiers in the new project.

Restore is rejected with 409 if the target contains active records or a source record from an earlier bundle restore. This workflow does not combine a bundle with an existing project. Restore creates new identifiers and remaps relationships; do not assume technical identifiers will remain unchanged.

Settings preference

ayarlar=paket is the default. Transferable bundle settings, such as coordinate system, local transformation, appearance and label templates, are applied. ayarlar=proje preserves existing target values; missing target values may be filled from the bundle. Differences are reported in settings_conflicts.

Administrator permission may be required for allocation rules, fiber-class exceptions, optical profiles/selections or label templates. If a required module is disabled, its content is not silently discarded; restore is rejected.

Result, validation and revert

A successful response contains ok, batch, counts, settings, settings_conflicts and, where needed, uyarilar. Restore runs in one database transaction. Rejected record or relationship validation leaves no partial restore.

The compressed upload is limited to 300 MiB and expanded JSON to 1,536 MiB. Content and permission checks apply independently, so files below these sizes are not necessarily accepted.

This endpoint does not accept the general request_id mechanism. If the response is lost, inspect the target project and history. Repeating a successful upload is rejected by the non-empty target check. POST /api/p/{pid}/changes/{batch}/revert can undo the restore; subsequent changes and dependencies may prevent it.

The ZIP package of field reports is a separate format described in Outputs API.