A missing marker, distorted polygon, or empty map is often caused by a small data mistake rather than a mapping-library bug. This GeoJSON and map data QA workflow gives you a repeatable way to validate geometry, coordinate systems, properties, encodings, and tiles before you debug the frontend. Use the checklist when importing a dataset, changing providers, or investigating features that are misplaced or absent.
Overview
Map data quality assurance is the process of proving that a dataset is structurally valid, geographically correct, and compatible with the format expected by your web map. It applies to GeoJSON, CSV files with coordinates, Shapefiles, GeoPackages, vector tiles, and MBTiles.
The fastest way to troubleshoot GeoJSON missing features is to separate the problem into layers:
- File layer: Can the file be read, parsed, and decoded?
- Geometry layer: Are the geometry types and coordinate arrays valid?
- Location layer: Are coordinates in the expected order and coordinate reference system?
- Schema layer: Do feature properties use the names and value types your application expects?
- Rendering layer: Does the map library, style, filter, source, or tile pipeline display the data correctly?
Testing in this order prevents you from changing map code when the actual fault is an invalid polygon or a latitude-longitude swap. For background on coordinate systems, see Web Mapping Coordinate Systems: EPSG:4326, Web Mercator, and Coordinate Conversion. For GeoJSON structure and geometry rules, use GeoJSON Explained: Coordinates, Geometry Types, Validation, and Common Mapping Errors.
A compact QA checklist
- Keep an untouched copy of the source data.
- Confirm the file encoding and format.
- Parse the data before opening it in a map.
- Validate GeoJSON structure and geometry.
- Check the bounding box and coordinate order.
- Confirm the source CRS and convert deliberately when needed.
- Inspect required property names and value types.
- Test a small fixture with known coordinates.
- Render without filters, clustering, or styling complexity.
- Validate generated tiles and their zoom and bounds.
- Record the command, tool version, input file, and result.
What to track
1. Parsing, encoding, and file integrity
Start by confirming that the file is the file you think it is. A JSON formatter can make a valid document easier to inspect, but formatting does not repair invalid syntax. Check for truncated downloads, an HTML error page saved with a .json extension, a byte-order mark that affects a fragile parser, and unexpected character encoding.
For a quick Node.js parse check:
node -e "const fs=require('fs'); const p=process.argv[1]; const data=JSON.parse(fs.readFileSync(p, 'utf8')); console.log(data.type, data.features?.length ?? 'not a FeatureCollection')" data.geojsonFor large files, avoid loading the entire dataset into memory until you know its size and structure. Inspect a sample first, then use a streaming or command-line workflow appropriate to the format.
2. GeoJSON structure and geometry validity
A web map commonly expects a FeatureCollection containing Feature objects. Each feature should have a geometry with a supported type and correctly nested coordinate arrays. A Point has one coordinate pair; a LineString has an array of positions; a Polygon has an array of linear rings. Polygon rings must be closed, meaning the first and last positions match.
Use a validator such as geojsonhint or a geometry library such as Turf for a first pass. The exact command may vary by installed package version, so treat the output as a diagnostic rather than a complete QA result:
npx geojsonhint data.geojsonFor programmatic checks with Turf:
import fs from 'node:fs';
import { featureEach } from '@turf/meta';
import booleanValid from '@turf/boolean-valid';
const collection = JSON.parse(fs.readFileSync('data.geojson', 'utf8'));
featureEach(collection, (feature, index) => {
if (!booleanValid(feature)) {
console.error(`Invalid geometry at feature ${index}`);
}
});Geometry validity is not the same as business correctness. A polygon can be technically valid but located in the wrong country, duplicated, or missing a hole. Add domain checks for expected feature counts, minimum area, known IDs, and acceptable bounds.
3. Coordinate order, bounds, and projection
GeoJSON positions use [longitude, latitude] order, not [latitude, longitude]. This is one of the most common causes of mislocated features. A quick range check can reveal a swap: longitude normally falls between -180 and 180, while latitude falls between -90 and 90. Range checks alone are not enough, however; both values may remain in range after being swapped.
Inspect the bounding box and plot a few known points. If a dataset intended for one city appears in another region, compare its source documentation and CRS metadata. GeoJSON commonly represents geographic coordinates in WGS 84, while many projected datasets use a local or national CRS. Do not assume that a number such as 4326 is present in the file or that a map library will detect the source projection automatically.
Use GDAL to inspect a source file:
ogrinfo -so -al input.gpkgConvert deliberately with ogr2ogr when the target format and CRS are known:
ogr2ogr -f GeoJSON \
-t_srs EPSG:4326 \
output.geojson input.gpkg layer_nameFor a broader explanation of EPSG:4326 and Web Mercator, refer to the coordinate systems guide linked above. Preserve the original data and document every conversion so a later user can reproduce it.
4. Topology and duplicate features
Topology problems become especially visible with administrative boundaries, parcels, and connected line networks. Look for self-intersections, unclosed rings, overlapping polygons, gaps, sliver polygons, duplicate features, and lines whose endpoints nearly touch but do not share the same coordinate.
Do not automatically “repair” every geometry in production. A repair operation can change boundaries or remove detail. First identify the affected feature IDs, compare the repaired output with the source, and define an acceptance rule. For example, you may accept a small correction to a self-intersecting ring but reject an unexpected change in area.
5. Properties and application schema
Many apparent rendering bugs are property mismatches. Your frontend may filter on properties.status while the source uses properties.Status, or it may expect a number while the imported value is the string "12". Check required fields, capitalization, null handling, unique identifiers, and date formats.
Test the schema with a small script:
const required = ['id', 'name', 'status'];
for (const [index, feature] of collection.features.entries()) {
for (const key of required) {
if (!(key in (feature.properties ?? {}))) {
console.warn(`Feature ${index} is missing ${key}`);
}
}
}Keep display properties separate from stable identifiers. A label can change; an ID used for joins, updates, or event handling should remain predictable.
6. Tiles, MBTiles, and source configuration
If raw GeoJSON looks correct but vector tiles are empty, inspect the tile-generation stage. Common causes include an incorrect input layer name, an output bounds setting that excludes the data, a zoom range that does not cover the map view, invalid geometry discarded during conversion, or a mismatch between the generated layer name and the style source-layer name.
Inspect an MBTiles file with a SQLite client:
sqlite3 data.mbtiles "select name, value from metadata;"
sqlite3 data.mbtiles "select min(zoom_level), max(zoom_level), count(*) from tiles;"Check the tile URL, source ID, source-layer, and style filters together. A layer can be present in a tile but invisible because its style filter excludes every feature. For render performance and tile-loading diagnostics, see Web Map Performance Audit.
Cadence and checkpoints
Run the full QA workflow whenever you import a new dataset, change a provider, alter a CRS, regenerate tiles, or modify a property-dependent style. For stable feeds, a lighter recurring check can run monthly or quarterly, depending on how often the source changes.
At ingestion
- Save the source URL or file name, retrieval time, and expected CRS.
- Record the feature count and a representative sample.
- Run parsing, geometry, bounds, and schema checks.
- Reject or quarantine data that fails critical checks instead of silently publishing it.
After transformation
- Compare feature counts before and after conversion.
- Compare bounds and a few known feature coordinates.
- Check that IDs and required properties survived.
- Validate the output format and inspect generated tile metadata when applicable.
Before release
- Render the data with filters disabled.
- Test representative points, lines, and polygons at relevant zoom levels.
- Open browser DevTools and check network responses, console errors, and source configuration.
- Test a deliberately invalid fixture to confirm that your error reporting works.
Keep these checks in version control alongside the transformation script. A small fixture is often more useful than a huge production file when reproducing a regression. The guide to testing mapping APIs locally covers fixtures, mocked responses, and browser debugging techniques.
How to interpret changes
Use a prioritized triage flow rather than changing several variables at once:
- Nothing loads: inspect the HTTP status, response body, content type, URL, and parser error.
- The map loads but no features appear: remove filters and styles, confirm the source is attached to the map, and fit the view to the data bounds.
- Features appear in the wrong place: check coordinate order, source CRS, axis assumptions, and units.
- Only some features are missing: inspect invalid geometries, null coordinates, property filters, feature IDs, and zoom-dependent styling.
- Raw data works but tiles do not: compare tile bounds, zoom range, layer names, generated metadata, and source-layer configuration.
- Features look correct but interactions fail: inspect IDs, property names, hit-testing settings, and whether the rendered layer is interactive.
For Leaflet, log the data before calling L.geoJSON and temporarily add a visible style or marker for each geometry type. For Mapbox GL JS, inspect the source and source-layer names, listen for source or style errors, and use a simple unfiltered layer before restoring production styling. For either library, fit the viewport to the dataset rather than relying on a hard-coded center while debugging.
Also distinguish data errors from API and browser errors. A CORS failure or authorization response can prevent valid data from reaching the parser. Use the Frontend API Debugging Checklist when the network request fails before map rendering begins.
Sample fixtures for repeatable tests
Maintain a small fixture set containing: one known Point, a LineString with two or more positions, a closed Polygon, a multipolygon, an intentionally swapped coordinate pair, an invalid self-intersecting polygon, a feature with missing properties, and an empty FeatureCollection. These cases let you verify both successful rendering and useful failure messages.
Example known point:
{
"type": "Feature",
"properties": { "id": "known-point", "status": "test" },
"geometry": { "type": "Point", "coordinates": [-73.9857, 40.7484] }
}Use a fixture coordinate only as a test value; do not infer the accuracy of an external dataset from a single point. The goal is to know exactly where the test feature should appear and whether the full pipeline preserves it.
When to revisit
Revisit this checklist on a monthly or quarterly schedule for recurring feeds, and immediately after any event that can change data or rendering: a provider migration, a new export process, a CRS conversion, a library upgrade, a tile-generation change, or a schema update.
Refresh the workflow when your validator, GDAL installation, Turf packages, Leaflet integration, or Mapbox GL JS integration changes behavior. Verify command syntax and configuration against the versions used by your project rather than copying an old command blindly. Recheck projection guidance when source systems introduce new CRS metadata or export options.
When a production issue occurs, preserve the failing input and record:
- the source file or request fixture;
- the map library and relevant package versions;
- the CRS and transformation commands;
- the observed bounds and feature count;
- the browser console and network symptoms;
- the smallest change that fixed the issue.
That record turns a one-off missing-feature bug into a reusable regression test. Before the next import, run the compact checklist, compare the new results with the previous baseline, and investigate changes in count, bounds, geometry validity, property coverage, or tile metadata. If the data passes but the map still fails, move on to provider configuration, API access, or frontend rendering rather than repeatedly repairing the dataset. For related work on geocoding, markers, and reverse geocoding, see the geocoding API integration guide.