Releases and pack manifests

Release document #

Prerequisites: maps scope. Fetch current through releaseInfo(), then retain its release ID with cached data. This example lists the document’s structure; sizes/checksums are illustrative placeholders, not values to copy.

{
  "schemaVersion": 1,
  "release": "mapdata-YYYYMMDD",
  "created": "ISO_TIMESTAMP",
  "data": { "osm": { "downloaded": "ISO_TIMESTAMP", "sha256": "HEX_SHA256" }, "region": "philippines" },
  "urls": { "files": "maps/v1/releases/mapdata-YYYYMMDD/files/", "packs": "maps/v1/packs" },
  "mapBase": { "token": "__MAP_BASE__", "online": "maps/v1/releases/mapdata-YYYYMMDD/files" },
  "styles": [], "layers": [], "sprites": [],
  "fonts": { "glyphs": "fonts/{fontstack}/{range}.pbf", "fontstacks": [] },
  "depth": null, "packs": [],
  "packLimits": { "boxNm": 90, "shoreNm": 10, "shoreBoxes": 8,
    "packBytes": 75000000, "gridDeg": 0.05, "baseMaxzoom": 14, "shoreZoom": 15 }
}

The actual urls also name the release document, checksums, signature and services. Each layer/style/sprite entry carries a file path, relative url, bytes and sha256 as applicable. Layer entries give id, kind, zooms, bounds and tileType; DEMs add encoding, vector overlays can add sourceLayer, and GMRT identifies its base. Styles expose styleUrl for server-resolved content. fonts identifies glyph templates and available stacks. depth gives decoding information and GEBCO grid provenance when built.

A URL for SHA256SUMS.sig does not establish that a signature file exists; unsigned development releases may omit it. Signature verification needs a trusted platform public key and a separate verification workflow.

Pack document #

{
  "schemaVersion": 1, "packId": "YYYYMMDD-PACK_ID", "kind": "mission",
  "release": "mapdata-YYYYMMDD", "created": "ISO_TIMESTAMP",
  "bbox": [123.6, 10.1, 124.1, 10.6], "shore": [],
  "zooms": { "base": { "minzoom": 0, "maxzoom": 14 } },
  "layers": [{ "id": "base", "kind": "vector", "file": "tiles/base.pmtiles" }],
  "styles": [{ "id": "dark", "file": "styles/dark.json" }],
  "mapBase": "__MAP_BASE__",
  "fonts": { "file": "fonts.tar", "fontstacks": [], "ranges": [], "glyphs": "fonts/{fontstack}/{range}.pbf" },
  "places": { "file": "places.json", "count": 0, "kinds": {} },
  "files": [{ "path": "tiles/base.pmtiles", "bytes": 123, "sha256": "HEX_SHA256" }],
  "totalBytes": 123
}

This abbreviated example omits most files and optional fields. Real layer entries include name, minzoom, maxzoom, bounds and tile count. Packs may include name, shoreZoom, notice and attribution. places is optional for compatibility with older packs; the file can validly contain zero points. totalBytes sums listed downloaded files and does not include the extra space needed to extract fonts. Never substitute example checksums or sizes.

Two file URL rules #

// On-demand API response: file.url is relative to the maps root.
const onDemandUrl = new URL(file.url, 'https://maps.example/').href;
// Stored/prebuilt manifest: file.path is relative to that manifest's URL.
const prebuiltUrl = new URL(file.path, manifestUrl).href;
// Neither URL uses the API portal's origin unless it is also your maps root.

Keep pack files under the same pack ID and release. Do not combine a newer style with older archives or replace a single file in an activated directory. Discover, download into staging, verify, then atomically switch your application’s active-pack record. Keep the previous pack until activation succeeds.

Freshness and compatibility #

Compare releaseInfo().release with the stored pack release when a connection returns. created is packaging time; data.osm.downloaded is an OSM source date. Bathymetry datasets have independent vintages. There is no automatic staleness policy in v1: your application chooses when to offer an update and must show users which release is offline.

The deployment policy recommends retaining the latest two releases, but clients must handle missing older releases and cache eviction. v1 changes should be additive; package breaking changes require a new major version. Do not assume all service responses have a manifest-style schemaVersion field.