Validate and Hash a Pack

Prerequisites

• spatialpack CLI installed (pip install -e ".[full]")
• A built Spatial Pack (a directory containing spatialpack.json and layer files)

Steps

1. Validate the pack manifest

Run the validator to check the spatialpack.json manifest against the JSON Schema. The validator examines structural validity, verifies that every declared layer file exists on disk, and checks license and provenance metadata.

spatialpack validate ./my-pack

Expected output:

Pack Validation Report
  Pack:        spatial.properties:wa:solar-feasibility:v1
  Version:     2025.01.31
  Status:      PASS

Checks:
  Schema conformance:    PASS
  Layer files exist:     PASS (6/6 layers)
  License completeness:  PASS
  Provenance:            PASS

Result: Conformant

A PASS status means the pack conforms to the Spatial Pack schema and all declared files are present.

2. Run strict validation

Strict mode treats warnings as errors. Use this before publishing to catch issues that the default mode tolerates.

spatialpack validate ./my-pack --strict

Expected output:

Pack Validation Report
  Pack:    spatial.properties:wa:solar-feasibility:v1
  Status:  PASS (strict)

All checks passed with zero warnings.

In strict mode, a missing optional field that would produce a warning in default mode causes the validation to fail.

3. Export a conformance report

Generate a machine-readable JSON conformance report for automated workflows, CI pipelines, or audit trails.

spatialpack validate ./my-pack -o report.json

Expected output:

Conformance report written to: report.json

The JSON report includes the validation status, individual check results, timestamps, and the validator version. This file can be stored alongside the pack for governance documentation.

4. Compute BLAKE3 hashes for a single file

Compute the BLAKE3 hash of an individual file. BLAKE3 hashes serve as integrity fingerprints — if a file changes by even one byte, the hash changes completely.

spatialpack hash file ./my-pack/layers/cadastre.parquet

Expected output:

BLAKE3 Hash
  File:  cadastre.parquet
  Hash:  blake3:a4f7c2e1b8d93f6...
  Size:  24.8 MB

Tip

Why BLAKE3 over SHA-256? BLAKE3 is a modern cryptographic hash function that is significantly faster than SHA-256 while providing equivalent security. On large spatial files (hundreds of megabytes), BLAKE3 completes in seconds where SHA-256 takes minutes. The blake3: prefix in the hash output makes the algorithm explicit, preventing confusion with other hash formats.

5. Compute hashes for all pack assets

Scan the entire pack and compute BLAKE3 hashes for every file in the rasters/ and layers/ directories.

spatialpack hash pack ./my-pack/

Expected output:

Pack Hashes
  Pack:     spatial.properties:wa:solar-feasibility:v1

  Asset Hashes:
    terrain_dem.tif       blake3:3b8f1a2c...
    terrain_slope.tif     blake3:7d4e9f6a...
    cadastre.parquet      blake3:a4f7c2e1...
    cadastre.pmtiles      blake3:9c1b3d5e...
    roads.parquet         blake3:6f2a8b4c...
    roads.pmtiles         blake3:e3d7c9a1...

  Total: 6 assets hashed

This gives you a complete integrity snapshot of the pack at a point in time.

6. Update the manifest with computed hashes

Write the computed hashes into the spatialpack.json manifest. This embeds the integrity information directly into the pack metadata.

spatialpack hash pack ./my-pack/ --update-manifest

Expected output:

Pack Hashes
  Assets hashed:     6
  Manifest updated:  ./my-pack/spatialpack.json

  integrity:
    asset_hashes:
      terrain_dem.tif:    blake3:3b8f1a2c...
      cadastre.parquet:   blake3:a4f7c2e1...
      ...

After this step, the spatialpack.json file contains hash values for every asset. Consumers can verify these hashes to confirm the pack has not been tampered with.

7. Verify hashes against the manifest

Check that the current file contents match the hashes recorded in the manifest. This detects any modifications, corruption, or tampering since the hashes were computed.

spatialpack hash verify ./my-pack/

Expected output:

Hash Verification
  Pack:     spatial.properties:wa:solar-feasibility:v1
  Status:   PASS

  All 6 assets match their manifest hashes.

If any file has been modified, the verification reports which files have changed:

Hash Verification
  Pack:     spatial.properties:wa:solar-feasibility:v1
  Status:   FAIL

  Mismatched:
    cadastre.parquet  expected blake3:a4f7c2e1... got blake3:f8b2d1a3...

8. Use strict verification

Strict mode additionally fails if any asset file exists in the pack but is not listed in the manifest’s hash table.

spatialpack hash verify ./my-pack/ --strict

This catches scenarios where new files have been added to the pack directory without updating the manifest.

9. Understand the governance workflow

Validation and hashing fit into a specific point in the pack lifecycle:

1. Build — The pipeline creates layers and a manifest.
2. Validate — Check the manifest against the JSON Schema and verify layer files exist.
3. Hash — Compute BLAKE3 hashes and write them into the manifest.
4. Publish — Upload the validated, hashed pack to a CDN at an immutable versioned path.

This sequence ensures every published pack is structurally valid, has complete metadata, and has cryptographic integrity verification. Consumers can verify the hashes after downloading to confirm nothing changed in transit.

# Complete governance workflow
spatialpack validate ./my-pack --strict
spatialpack hash pack ./my-pack/ --update-manifest
spatialpack validate ./my-pack --strict   # Re-validate after hash update

Next steps

• CLI validate reference — Full options for spatialpack validate
• CLI hash reference — Full options for spatialpack hash commands
• Pack Lifecycle — The complete build-validate-publish workflow