Matching reference numbers can be necessary without proving that the coordinates are right
Two GeoPackages use the same numeric spatial-reference identifier. A merge process treats the layers as equivalent, but the points no longer line up. The number may be a local reference within each package rather than a universal definition. Or the declarations may agree while the underlying coordinates were labelled incorrectly in the first place.
This guide follows the reference chain from a GeoPackage’s SRS table to its geometry-column declaration and individual geometry headers. It distinguishes a valid reference relationship from correct numerical coordinates, and a metadata correction from a real coordinate transformation. The purpose is an evidence-based audit, not a recipe for editing spatial binary data by hand.
All custom identifiers, coordinate frames and numerical fixtures below are fictional. They are not registered EPSG definitions or surveys of actual places. Operational repairs require authorised test copies, compatible GeoPackage-aware software, the applicable published specification and independent evidence for the intended reference.
Geoinformatics subject guide · Learning that transfers into life · How X Works hub
Choose your reading route
Route 1: Follow the reference chain · Chapters 1–3
Route 2: Work a local-identifier collision · Chapters 4–5
Route 3: Separate correction and conversion · Chapters 6–8
Distinguish assigning a reference from transforming coordinates
Route 4: Validate without overclaiming · Chapters 9–10
Route 5: Transfer and hand off · Chapters 11–12
Full chapter index · Independent worked case · Questions and practical checks
Chapter index
Follow the reference chain · Chapters 1–3
Read the package as a connected spatial database
Distinguish local SRS keys from authority identifiers
Trace geometry-column and geometry-header declarations
Work a local-identifier collision · Chapters 4–5
Build two explicit fictional coordinate frames
Compare identifier agreement with location agreement
Separate correction and conversion · Chapters 6–8
Distinguish assigning a reference from transforming coordinates
Use independent controls rather than circular agreement
Treat undefined references as information limits
Validate without overclaiming · Chapters 9–10
Inspect dimensions, units and related declarations
Validate the repaired copy through a round trip
Transfer and hand off · Chapters 11–12
Transfer to a service response or another file format
Make the handoff distinguish facts from repairs
CHAPTER 1 OF 12
1. Read the package as a connected spatial database
A GeoPackage is not merely a collection of coordinate arrays. Its tables describe which user tables contain spatial information, which columns hold geometry and which reference systems give that geometry meaning. An individual geometry also carries a reference identifier in the GeoPackage geometry header.
The reference chain matters because coordinates alone are ambiguous. The pair(100,200) could represent a location in an invented local plane or another coordinate representation entirely. A reader needs the associated definition, axes and units before interpreting or combining it with another layer.
Think of a catalogue key pointing to a definition. The key’s job is to connect records within a system. The definition’s job is to explain the reference. Confusing the two can make identical-looking identifiers seem like proof of identical geographic meaning when they are not.
Start the audit by identifying the package version, relevant feature table, geometry column and SRS definition. Then inspect how those declarations connect to actual geometries. This establishes the intended interpretation before any attempt to decide whether the points are in the correct real-world places.
CHAPTER 2 OF 12
2. Distinguish local SRS keys from authority identifiers
The gpkg_spatial_ref_sys table uses srs_id as a primary key referenced elsewhere in the package. It also carries an organisation and an organisation-assigned coordinate-system identifier, together with the reference definition. Those fields have related but different jobs.
The published GeoPackage specification warns clients not to make unsupported assumptions about arbitrary SRS IDs. Some required values have defined meanings, but that does not make every numeric key a universal EPSG identifier. The same custom local number in two different packages requires definition-aware comparison.
For a fictional collision fixture, package A uses local key99001 for classroom frame Alpha and package B uses99001 for classroom frame Beta. The key text matches. If the definitions differ, matching the keys alone does not establish reference equivalence. The collision is between namespaces, not necessarily a damaged row within either original package.
Do not respond by inventing an authority code for a custom reference. Preserve the original definition and identify what is known, unknown or undefined under the applicable standard. A convenient label can help a person discuss a dataset, but it cannot replace a formally justified coordinate-system identity.
CHAPTER 3 OF 12
3. Trace geometry-column and geometry-header declarations
The gpkg_geometry_columns table identifies a feature table’s geometry column and its declared spatial-reference identifier. Under the specification’s reference-consistency requirement, geometries in that column must use the identifier declared for the column. The header and column are therefore connected evidence, not independent free-form labels.
A package can contain more than one spatial layer, so inspect the declaration for the actual column being analysed. A different layer’s reference is not a safe default. The catalogue and reference tables need to remain coherent with the particular geometry records returned to the client.
Construct a tiny test table whose declared reference key is99001. Give two geometries matching headers and one a conflicting99002 header. The first question is structural consistency: does each geometry agree with the column contract? That question can be answered separately from whether either custom definition describes a real location correctly.
Use a compatible spatial reader or validator rather than changing header bytes in a hex editor. The numerical identifier is only part of a geometry’s binary representation. A repair that makes one visible number look right can corrupt other structure or leave associated metadata and indexes inconsistent.
CHAPTER 4 OF 12
4. Build two explicit fictional coordinate frames
Let frame Alpha use coordinates(u,v). Let frame Beta represent the same classroom plane by x=100+2u and y=200+3v. The inverse is u=(x−100)/2 and v=(y−200)/3. These are deliberately simple affine equations, not real projection or datum transformations.
A point P at Alpha(4,5) has Beta(108,215). A second point Q at Alpha(8,2) has Beta(116,206). Their identities and physical classroom positions are unchanged; only their numerical representation changes. The equations make that correspondence independently checkable.
Now suppose both original packages used local key99001, one for Alpha and one for Beta. If a merger retains one definition and imports the other coordinates unchanged under that definition, either P=(4,5) or P=(108,215) will be interpreted incorrectly. Equal keys did not make the input numbers equivalent.
A safe merge must preserve or correctly map the reference definitions and perform any required actual transformation. It must not merely choose whichever definition appears first. The identity of a spatial reference and the transformation between two references are separate pieces of information needed by the combined result.
CHAPTER 5 OF 12
5. Compare identifier agreement with location agreement
Consider two checks. The first asks whether every geometry header agrees with its column’s declared reference key. The second asks whether known objects appear at independently justified positions under that reference. Passing the first does not logically imply passing the second.
For an invented failure, store P’s Beta numbers(108,215) in a column consistently declared Alpha, with a matching Alpha header. All internal reference labels can agree. The record is nevertheless misinterpreted under the classroom definitions because Alpha P should be(4,5). Consistency has preserved the wrong interpretation uniformly.
Conversely, a geometry can carry numerically appropriate coordinates while its header disagrees with the declared column. A particular viewer may appear to place it correctly because of a chosen override, but the file still contains a contract conflict. A screenshot cannot substitute for inspecting the actual declarations.
Keep both tests in the acceptance record. Internal consistency supports interoperability; independent location evidence supports geographic correctness. The two are complementary. Calling either one complete CRS validation risks hiding exactly the failure the other check was designed to reveal.
CHAPTER 6 OF 12
6. Distinguish assigning a reference from transforming coordinates
Assigning a reference changes how existing numbers are interpreted. Transforming coordinates changes the numerical representation under a known source-to-target relationship. These operations can be appropriate in different diagnoses, but they must not be treated as interchangeable buttons for making layers line up.
If P’s correct Alpha numbers(4,5) are merely missing their Alpha declaration, restoring the correct declaration can be a metadata correction without changing the numbers. If P must instead be represented in Beta, the correct conversion produces(108,215). Assigning the Beta label to unchanged(4,5) does not perform that conversion.
If the source was already mislabelled, transforming under the wrong source interpretation can compound the error. Establish the intended source reference from trustworthy provenance before applying a transformation. Do not infer it solely by trying several labels until one creates a visually pleasing overlay.
Work on an authorised copy and preserve the original evidence. Record whether the operation corrected a declaration, transformed coordinates or repaired a source error. The distinction explains why the numbers did or did not change and lets a later reviewer reproduce the intended geographic interpretation.
CHAPTER 7 OF 12
7. Use independent controls rather than circular agreement
A transformation check needs an independent basis. Comparing two displays that both read the same incorrect declaration can produce reassuring agreement without validating the real positions. Agreement is useful only after understanding which assumptions and source information the methods share.
For the classroom fixture, calculate P and Q directly from the stated equations and compare them with the converted output. Use asymmetric points so an axis swap is detectable. Add a third point away from the first two to expose errors that happen to cancel at one location.
For real geography, appropriate control evidence can include trusted survey or provider reference information, suitable landmarks and a justified transformation pipeline. The acceptable discrepancy depends on the source quality, reference definitions, conversion method and intended use. This article does not provide a universal tolerance for all datasets.
Keep numerical conversion error distinct from measurement uncertainty. A consistently transformed uncertain observation remains uncertain. A broad survey uncertainty should not be used to excuse an obvious reference mismatch. Diagnose each uncertainty layer before deciding what the output can responsibly support.
CHAPTER 8 OF 12
8. Treat undefined references as information limits
GeoPackage includes defined conventions for undefined Cartesian and undefined geographic references. An undefined reference is not permission to guess a convenient known system. It records a limit on what the package establishes about coordinate interpretation.
An invented local engineering sketch may use coordinates useful within its own diagram while lacking a justified connection to an Earth-referenced system. Its internal distances can still be meaningful under documented units and assumptions. Plotting it over a national basemap requires additional reference evidence that the sketch alone may not provide.
Do not invent that connection by choosing a familiar country or copying a nearby layer’s CRS. A geographic location that looks plausible is not independent proof. Preserve the undefined state and seek authorised source documentation or suitable control information before making stronger spatial claims.
A good explanation can still be useful when certainty is limited. It can state which comparisons are supported internally, which cross-layer operations remain unjustified and what evidence would resolve the gap. Honest uncertainty is more helpful than an apparently complete file whose reference was chosen by trial and error.
CHAPTER 9 OF 12
9. Inspect dimensions, units and related declarations
A coordinate reference is more than a horizontal label. Dimensions and unit meanings need attention, especially where geometries carry elevation or measures. The specification distinguishes the presence of Z and M values from geometry type and provides rules for reference declarations.
Do not assume every third number is a universally comparable height or every fourth number is time. Read the actual reference and product contract. A coordinate array can be structurally readable while its extra values remain unsuitable for the intended comparison.
For a fictional example, two layers use the same horizontal classroom plane but one stores height in a different local convention. Their plan-view points can align while a three-dimensional distance calculation is wrong. A successful two-dimensional overlay is therefore not a complete dimensional validation.
Check the relevant table and metadata declarations as a connected set, including the geometry column and package contents where applicable. Correcting one field while leaving contradictory declarations elsewhere can preserve interoperability failures. A compatible validator helps identify structural relationships, while domain evidence determines the intended reference meaning.
CHAPTER 10 OF 12
10. Validate the repaired copy through a round trip
After an approved correction or transformation, close the writer and reopen the saved package with the intended reader. Inspect the saved reference definitions, column declarations, geometry headers and representative coordinates. The in-memory preview is not the final delivered object.
Compare expected IDs and counts before and after. A correct coordinate conversion should not silently drop objects or duplicate them. Check null and empty geometries under the applicable rules rather than treating every unusual record as disposable. Source population preservation is separate from coordinate correctness.
Also evaluate derived structures affected by geometry changes. Spatial indexes and cached extents may need supported maintenance. The connected RTree guide explains how an internally valid search structure can still drift from current source geometry. Rebuilding an index does not resolve a wrong CRS, and correcting a CRS does not prove every derived structure is current.
Retain the processing recipe, software version, source and target definitions, validation results and independent control checks. If a transformation resource is unavailable or unsupported, report that limitation rather than silently substituting a different operation. The delivered package should carry an interpretation the receiving team can reconstruct.
CHAPTER 11 OF 12
11. Transfer to a service response or another file format
An API response can express the same objects in a negotiated output CRS. The reference chain then includes request parameters and response declarations rather than only GeoPackage tables. The need to keep labels, numbers and recipient expectations aligned remains unchanged.
A different file format may have another way of storing reference information or may rely on an external agreement. Exporting a layer does not automatically preserve every reference detail. Inspect what the target format can represent and what the actual exporter saved.
For a changed-context exercise, export our fictional Beta coordinates to a plain table containing only x and y. The numbers remain intact, but a recipient who assumes Alpha interprets them incorrectly. A successful byte transfer has not preserved a complete geographic interpretation. The missing piece is the reference contract.
The transferable principle is connected meaning, not a universal metadata field name. GeoPackage srs_id, an API Content-Crs declaration and a documented table schema can play related roles in different systems. Their exact rules and identity scopes still need to be established separately.
CHAPTER 12 OF 12
12. Make the handoff distinguish facts from repairs
A useful handoff identifies the original package and layer, original reference evidence, diagnosed conflict, authorised action and final validated state. It should say whether numbers changed and why. A note reading CRS fixed does not reveal enough to distinguish a metadata correction from a transformation.
For the classroom merge, the record can say: packageA local key99001 defined Alpha; packageB local key99001 defined Beta; packageB coordinates were converted using the stated fictional inverse before both layers were delivered in Alpha. P then agrees at(4,5) and Q at(8,2). The custom local key collision was resolved without pretending it was a shared authority definition.
For a real project, preserve authoritative definitions and suitable evidence instead of this toy recipe. Do not present a passing classroom fixture as an official conformance certificate or engineering approval. The published standard, implementation tests and geographic source evidence each retain their separate authority.
The practical endpoint is a package whose references can be followed and whose locations can be justified. You should be able to explain what each identifier points to, why the declarations agree, whether coordinates were actually transformed and what independent check supports their interpretation.
A practical review begins with a reference ledger rather than a repair button. For each input layer, record its package identity, local reference key, declared authority where known, definition, geometry-column declaration and representative geometry-header interpretation. Keep original values in the ledger even when the final delivery uses another reference. This separates what arrived from what the approved processing operation produced.
The first test is a namespace collision test. Create two authorised classroom fixtures with the same custom local key and different explicitly fictional definitions. A merger should not infer equivalence from the shared number alone. The test passes when the definitions are preserved or correctly mapped and any required numerical conversion is justified. It fails when the program chooses one definition silently and leaves incompatible coordinates under that label.
The second test is a declaration-conflict test. Use one geometry whose header disagrees with its column declaration. The validator should expose the relevant inconsistency under its supported rules. A viewer’s convenient override should not erase the conflict from the evidence record. Record how the actual recipient reacts, because a file that appears correct under one override may be misinterpreted by another consumer that follows the declarations differently.
The third test is a consistently wrong-label test. Give every relevant declaration the same Alpha interpretation while storing a known Beta coordinate. Structural checks can pass, so independent control evidence must detect the numerical meaning problem. This is a deliberately adversarial fixture: it demonstrates why reference consistency and geographic correctness are separate acceptance conditions rather than two names for one check.
The fourth test is an identity-preservation test. Convert four expected objects and compare their IDs before and after. Then include one null geometry under the applicable data model and inspect how it is preserved. A coordinate operation should not silently convert that missing geometry into an origin point merely because the output needs a coordinate array. Location missingness requires its own documented treatment, not a guessed geometric repair.
The fifth test examines a receiving format with less explicit reference context. Export the verified classroom coordinates to a table and hand it to a colleague together with the final reference definition and operation history. Then repeat without that accompanying information. The difference reveals which parts of the interpretation depend on the handoff, even when the numerical values are unchanged. A lossless transfer of numbers can still be a lossy transfer of geographic meaning.
For the final acceptance statement, list the actual checks passed and their scope. State the dataset version, intended region, reference definitions, supported software and independent controls. Do not transform a small successful test into a claim that every future edit or every other geographic reference will work. A useful handoff leaves the receiving team with reproducible evidence and clear limits, rather than a vague assurance that the coordinates have been fixed.
Independent worked case and evidence checks
Try this independent fictional merge. PackageA stores P=(2,3) and Q=(5,7) in Alpha. PackageB stores R=(108,206) and S=(116,224) in Beta, where x=100+2u and y=200+3v. Both packages happen to use local key99001 for their own definitions.
Compute the Alpha equivalents of R and S. R becomes((108−100)/2,(206−200)/3)=(4,2). S becomes((116−100)/2,(224−200)/3)=(8,8). The merged Alpha population should therefore contain P=(2,3),Q=(5,7),R=(4,2),S=(8,8), with all four source identities retained.
An incorrect merge that preserves PackageB’s numbers but assigns Alpha to them places R at(108,206) and S at(116,224). A header-versus-column check can still pass if both were rewritten consistently. The failure appears only when the declared interpretation is compared with the independent transformation evidence.
Now introduce a different defect: give R’s geometry header the Beta key while the merged column declares Alpha. Even if its numeric position was already converted to(4,2), the file contains a reference conflict. The appropriate repair requires understanding which statement is wrong, not blindly changing coordinates again.
Check source preservation: two input records from each package should yield four expected IDs. A merged count of four is not enough if Q was dropped and R duplicated. Compare actual identities as well as reference declarations. Correct reference handling cannot compensate for an incomplete population.
For a changed-context test, suppose the source evidence later shows that PackageB’s numbers were already Alpha despite its Beta declaration. Applying the inverse Beta transformation would now be wrong. This demonstrates why diagnosis precedes conversion: the original label is evidence to inspect, not an infallible command that should override all other trustworthy source information.
Finally deliver only the four coordinate pairs without a reference description. The arithmetic remains correct inside the classroom exercise, but the recipient cannot reliably interpret the result from numbers alone. Add the final reference definition, operation history and a small independently checkable control set. That is what turns a successful calculation into a usable handoff.
Use two separate acceptance questions for this delivery. Can another reader follow every saved reference declaration without relying on an undocumented override? Can that reader reproduce the intended classroom positions from the supplied independent evidence? If the first answer is yes and the second is no, the package may be internally consistent but geographically unjustified. If the first is no and the second is yes only after an override, the file still needs a documented structural correction. Neither answer should disappear into a single vague pass mark.
Now change the recipient rather than the coordinates. A reviewer wants distance between P and R in the classroom Alpha plane. With P=(2,3) and R=(4,2), the displacement is(2,−1), so its length is the square root of5 Alpha units. Computing directly from unconverted R=(108,206) would answer a different and unjustified question. Even after correct conversion, the result remains a fictional planar distance in the stated units; it is not a survey distance on Earth. Reference handling enables a calculation, but the model and intended use still determine what that calculation means.
Worked comparison
| Evidence | What it establishes | What still needs checking |
|---|---|---|
| Local srs_id | Reference key within the package | Definition and authority identity |
| SRS definition | Intended coordinate meaning | Whether source numbers actually follow it |
| Column declaration | Reference contract for the geometry column | Agreement of individual headers |
| Matching headers | Internal reference consistency | Independent positional correctness |
| Round-trip and control checks | Saved interpretation under tested conditions | Limits beyond the tested area or task |
Questions and practical checks
Is every srs_id an EPSG code?
No. Inspect the package’s reference table and authority fields. Do not infer universal meaning from arbitrary local identifiers.
Do matching geometry and column IDs prove the points are right?
No. They establish an internal relationship, which can still consistently label wrong numerical coordinates.
Is assigning a CRS the same as reprojecting?
No. Assignment changes interpretation; transformation changes numerical representation under a justified relationship.
Can I repair geometry headers by hand?
Use compatible, authorised spatial tools and validated test copies. Binary edits can damage more than the visible identifier.
What should the receiving team get?
The final reference definition, source evidence, operation history, saved-file validation and appropriate independent checks.
Continue with the connected subjects
Keep storage and search consistent
GeoPackage RTree indexes: maintaining derived search evidence
GeoPackage structure: features, references and protected schema
Preserve meaning across handoffs
GeoPackage column descriptions: human help versus machine identity
GeoJSON: what a different exchange contract requires
Sources and scope
Published OGC GeoPackage1.4.0: SRS tables, geometry declarations and header consistency
GDAL GeoPackage driver: compatible reading, writing and validation
GDAL ogr2ogr: assignment and source-to-target reference operations
The numerical cases in this guide are original fictional teaching examples, not measurements from a real site. This is an educational explanation, not a field safety instruction, engineering approval or an official certification. For a real project, use qualified practitioners, current product documentation and site-specific evidence. Sources were checked on 30 October 2026.
Connect the representation checks
Each guide below addresses a different dependency. Use the one that matches the evidence you still need rather than treating any single successful check as complete validation.
CRS negotiation: selection coordinates versus returned positions. Follow the reference chain from input search bounds to returned positions and the next recipient.
STAC asset roles: discovery images versus measurement inputs. Check which available resource actually supplies the measurements, support and quality evidence required by the task.
GeoJSON null geometry: present records without map locations. Reconcile source records, supplied geometry and the map display before claiming completeness.