File formats
This section explains how each supported file format is handled, what format-specific options are available, and what to watch out for.
Comparison
| Format | Extension | Read | Write | Geometry | Attributes | Topology | Multi-layer |
|---|---|---|---|---|---|---|---|
| Shapefile | .shp |
✓ | ✓ | vector | DBF (10-char names) | — | — |
| GeoJSON | .json .geojson |
✓ | ✓ | vector | yes | — | — |
| TopoJSON | .json .topojson |
✓ | ✓ | vector | yes | ✓ | ✓ |
| GeoPackage | .gpkg |
✓ | ✓ | vector | yes | — | ✓ |
| FlatGeobuf | .fgb |
✓ | ✓ | vector | yes | — | — |
| KML / KMZ | .kml .kmz |
✓ | ✓ | vector | limited | — | ✓ |
| CSV / TSV | .csv .tsv |
✓ | ✓ | points (X/Y) | yes | — | — |
| DBF | .dbf |
✓ | ✓ | none | yes | — | — |
| JSON records | .json |
✓ | ✓ | none | yes | — | — |
| SVG | .svg |
✓ | ✓ | vector | as data-* |
— | ✓ |
| Mapshaper snapshot | .msx |
✓ | ✓ | vector | yes | ✓ | ✓ |
A few things worth knowing across all formats:
- Auto-detection by extension. You usually don't need to tell Mapshaper what format a file is — it picks the right reader from the file extension. Use
format=on-ior-oto override. - TopoJSON is the only interchange format that preserves topology in the file itself. Topology-aware operations like
-dissolve,-cleanand-simplifywork correctly regardless of the input format, but only TopoJSON keeps shared boundaries between adjacent polygons from being duplicated on disk. (Mapshaper's own.msxsnapshots also preserve topology, but they're not readable by other tools.) - Encoding. The
encoding=option on-iand-oapplies to Shapefile, DBF and CSV/TSV i/o (UTF-8 is the default) — the other formats are UTF-8-only.