Snapshot packages

A snapshot package is a set of data frozen at a date, self-contained with everything needed to read it: the data files, the code lists their coded fields use, a machine-readable description and a README. The same format serves two purposes:

• Example data on semanticgis.org, so that a worked example can be reproduced on anyone’s computer without API keys, with exactly the example’s numbers (Habitat network at Ledreborg (Example), Share of rented dwellings in Copenhagen (Example)).
• Datasets published to a research group, so that what the group analysed can be found and read again later, even after the source has changed.

Live access is a different case: there the SemanticGIS plugin reads current data, and the code lists follow the source’s schema version.

What a snapshot contains

<snapshot>/
  snapshot.json        machine-readable description (a STAC Item)
  data files           GeoParquet, GeoPackage, Cloud Optimized GeoTIFF (+ .qml styles)
  codelists/*.csv      one file per code list: code, name (name_en, description)
  README.txt           human-readable, generated from snapshot.json
  <name>_data.zip      everything above in one download

Choosing the data format

Data	Format	Why
Large point or table layers	GeoParquet (zstd)	column-wise storage compresses repeated values to almost nothing: 349,743 dwellings take 6.6 MB, against 39 MB as GeoPackage
Small sets of several vector layers	GeoPackage	one file, several layers, styles inside
Rasters	Cloud Optimized GeoTIFF with a .qml style of the same name	compressed, tiled, readable over the web; QGIS loads the style automatically

Layers are extracted for the area plus a margin. Vector features are kept whole — every feature that touches the area, not cut at its edge — so that selections by size or length give the same result as on the source.

Code lists

Coded fields keep their codes, as the source registers them. The names travel with the snapshot in codelists/, one CSV per list, with its source and the date it was retrieved (e.g. a BBR list from teknik.bbr.dk). The codes are the data; the code list is how to read them at that date, and lists change between versions of a register.

To see the names in QGIS, join the code list to the layer by code (Layer Properties › Joins). The SemanticGIS plugin will be able to do this automatically from snapshot.json.

snapshot.json

A STAC Item, so that the same description can be read by catalogues and by the plugin:

• properties: title, description, datetime (the date of the data), proj:code and proj:bbox (EPSG:25832), the sources with licence and attribution (semanticgis:sources).
• assets: each file, with
  • for tables, the table extension’s table:columns: name, type, description, and for a coded field semanticgis:codelist, the key of its code-list asset;
  • for categorical rasters, the classification extension’s classification:classes (value, name, title);
  • for each code list, its source and retrieval date.
• links: the examples or project pages that use the snapshot.

Licences and attribution

Every source is listed with its licence and the attribution line to put on a map, using the wording from the dataset’s page on semanticgis.org where it has been checked, and hentet ‹date› for downloaded data. A snapshot redistributes data, so the licence must allow it; where a source’s terms are not explicit, say so in the README.

Building a snapshot

In semanticGIS-code, scripts/snapshots.py builds the example snapshots: it extracts the data, fetches the code lists, writes snapshot.json, generates the README and zips the folder. New snapshots follow the same pattern.

The software environment

A snapshot fixes the data. The software can be fixed the same way, with an environment file or a container: see Reproducible environments.