FieldLayers `.magpkg` Contribution Format

Status: v1.1 schema for synthetic fixture testing and local exporter preparation. Public intake is not open.

The .magpkg format is an offline file contract for future contribution packages. A package contains anonymous aggregated magnetic grid-cell summaries generated on the contributor's device. It does not contain a route, exact sample timestamps, account identity, device identity, payment identity, or personal contact fields.

The v0.9 pipeline tests this format only with deterministic synthetic packages. No live people, phones, robots, or upload endpoint are involved.

Package Boundary

A contribution package may contain:

a random contribution_id that is not reused as a user identifier;
platform context such as platform_type, contribution_mode, observation_level_kind, and sensor class;
non-identifying calibration references, currently nullable;
cell aggregates: cell_id, median_nt, sample_count, confidence, and coarse monthly time_bucket;
optional v1.1 altitude summaries: median_altitude_m plus altitude_source (gps, baro_relative, or null);
notice_ack: true, meaning the package creator acknowledges the data is lawful to collect and share;
license: "CC0-1.0" for package payloads.

A contribution package must not contain:

name, email, account, phone number, IP address, device ID, advertising ID, payment identity, or persistent contributor identity;
raw GPS tracks, route geometry, ordered route, exact timestamps, raw samples, or magnetometer streams;
per-location leaderboard data or contributor-recognition history.

The schema uses additionalProperties: false at every object level. A package with an email field is rejected before aggregation.

Cell Grid

The grid encoding is fieldlayers_latlon_v1.

Formula:

cell_id = fl_<lat_index>_<lon_index>
lat_index = floor((lat + 90) / cell_size_deg)
lon_index = floor((lon + 180) / cell_size_deg)
cell_center_lat = lat_index * cell_size_deg - 90 + cell_size_deg / 2
cell_center_lon = lon_index * cell_size_deg - 180 + cell_size_deg / 2

The current synthetic fixtures use cell_size_deg = 0.01 in EPSG:4326.

Altitude v1.1

.magpkg schema 1.1 adds optional per-cell altitude summaries. These fields are

summary evidence, not a route:

median_altitude_m: median altitude/depth for samples contributing to that

cell, sanity-bounded to -500..9000 meters.

altitude_source: gps, baro_relative, or null.

For phone logger packages, gps means the phone's location altitude. It is not

barometric altitude, not corrected sensor height, and not a guarantee that every

sample in the cell was recorded at a single physical height. Packages without

altitude fields remain valid for backward compatibility.

.magpkg packages do not compute terrain-aware voxel bins. Future merge code

uses DEM context and vertical datum correction to derive ground_elevation_m,

height_agl_m, and vertical_bin in the canonical store. If DEM/geoid context

is missing, the merge pipeline must leave those fields null rather than deriving

vertical bins from GPS altitude alone. See VERTICAL_GRID_POLICY.md.

Validation Stages

The validator returns a structured report with package-level reasons and per-cell reasons. Schema-valid packages may be partially accepted: accepted cells can continue to aggregation while rejected cells are cut and reported.

Reason code	Level	Meaning
`schema_invalid`	package	JSON Schema failed or an identity/raw-route field was found.
`physics_implausible`	cell	A value, sample count, or confidence field is outside hard sanity bounds.
`physics_extreme_warning`	cell warning	`median_nt` is outside the warning range but inside the hard reject range.
`geo_invalid`	cell	`cell_id` cannot be decoded into a valid EPSG:4326 cell center.
`geo_ocean_or_unmapped`	cell	Street-level cell falls in the coarse fixture landmask's ocean/unmapped area.
`jurisdiction_not_allowed`	cell	Cell center is outside configured allowlist regions.
`region_restricted`	cell	Cell center intersects a configured restricted region.
`partial_accept`	package	At least one cell was accepted and at least one was rejected.
`no_accepted_cells`	package	No cells survived validation.

The v0.9 landmask and jurisdiction files are test mechanisms, not a public intake policy.

Aggregation Semantics

The synthetic aggregation step groups accepted cells by cell_id.

Cell value: weighted median of package cell medians.
Weight: confidence * sample_count.
total_samples: sum of accepted sample counts.
contributor_count: number of accepted packages contributing the cell, not number of people.
confidence_agg: sample-weighted mean confidence.

The output fixture layer is crowd_street_synthetic. It is not added to the public catalog or viewer because it is synthetic and not a real data product.

Current Boundary

Intake is not open. This document is published so early adopters can prepare compatible local exporters, but FieldLayers does not currently accept uploads, accounts, forms, API submissions, or live contribution streams.