# Detecting Breaking Changes in Spatial Contracts

The most expensive contract changes are the ones that look additive. A field renamed and re-added, a CRS swapped for an equivalent-looking one, an extent narrowed at the edges — each reads as a small diff and breaks a working consumer. This guide computes the structural diff between two contract versions, classifies it against a consumer-driven compatibility rule rather than a judgement call, and fails a release whose declared version does not match what the diff shows. It automates the classification step in Data Contracts for Spatial Products within Geospatial Data Mesh Fundamentals, extending Versioning Spatial Data Contracts with SemVer.

# Prerequisites

# Step-by-Step Implementation

# 1. Diff the two contracts structurally

# contract_diff.py — a structural diff over the clauses that can break a consumer.
import json


def index_attributes(contract: dict) -> dict:
    return {a["name"]: a for a in contract.get("attributes", [])}


def diff(old: dict, new: dict) -> list[dict]:
    """Every difference that can affect a conforming consumer, as a typed change.
    Cosmetic differences — description text, ordering — are deliberately ignored."""
    changes = []
    o_attrs, n_attrs = index_attributes(old), index_attributes(new)

    for name in n_attrs.keys() - o_attrs.keys():
        changes.append({"kind": "attribute_added", "name": name,
                        "required": n_attrs[name].get("required", False)})
    for name in o_attrs.keys() - n_attrs.keys():
        changes.append({"kind": "attribute_removed", "name": name})
    for name in o_attrs.keys() & n_attrs.keys():
        o, n = o_attrs[name], n_attrs[name]
        if o.get("type") != n.get("type"):
            changes.append({"kind": "attribute_type_changed", "name": name,
                            "from": o.get("type"), "to": n.get("type")})
        if not o.get("required", False) and n.get("required", False):
            changes.append({"kind": "attribute_became_required", "name": name})

    for field in ("crs", "geometry_type", "coordinate_precision"):
        if old.get(field) != new.get(field):
            changes.append({"kind": f"{field}_changed",
                            "from": old.get(field), "to": new.get(field)})

    o_ext, n_ext = old.get("extent"), new.get("extent")
    if o_ext != n_ext:
        # Narrowing removes coverage a consumer may be querying; widening does not.
        changes.append({"kind": "extent_narrowed" if _narrows(o_ext, n_ext)
                        else "extent_widened", "from": o_ext, "to": n_ext})
    return changes


def _narrows(old_bbox, new_bbox) -> bool:
    """True when the new extent fails to contain the old one on any side."""
    if not old_bbox or not new_bbox:
        return True
    return (new_bbox[0] > old_bbox[0] or new_bbox[1] > old_bbox[1]
            or new_bbox[2] < old_bbox[2] or new_bbox[3] < old_bbox[3])

Verify the diff is symmetric-aware — a rename must appear as a removal plus an addition, not as a benign pair:

python3 -c "
import contract_diff, json
old = {'attributes': [{'name': 'owner_ref', 'type': 'string'}], 'crs': 'EPSG:4326'}
new = {'attributes': [{'name': 'owner_reference', 'type': 'string'}], 'crs': 'EPSG:4326'}
print(json.dumps(contract_diff.diff(old, new), indent=2))"
# Both an attribute_removed and an attribute_added — which classifies as MAJOR.

# 2. Classify from the diff, not from intent

# classify.py — the rule is: if any conforming consumer can break, it is MAJOR.
MAJOR = {
    "attribute_removed", "attribute_type_changed", "attribute_became_required",
    "crs_changed", "geometry_type_changed", "extent_narrowed",
    "coordinate_precision_changed",
}
MINOR = {"attribute_added", "extent_widened"}


def classify(changes: list[dict]) -> str:
    kinds = {c["kind"] for c in changes}
    if kinds & MAJOR:
        return "MAJOR"
    # An added REQUIRED attribute breaks writers even though addition is usually minor.
    if any(c["kind"] == "attribute_added" and c.get("required") for c in changes):
        return "MAJOR"
    if kinds & MINOR:
        return "MINOR"
    return "PATCH"


def justify(changes: list[dict]) -> list[str]:
    """Human-readable reasons, so a MAJOR classification is arguable with evidence."""
    return [f"{c['kind']}: {c.get('name') or f'{c.get(chr(39)+chr(39))}'}" if False
            else f"{c['kind']}" + (f" ({c['name']})" if "name" in c else
                                   f" ({c.get('from')} -> {c.get('to')})")
            for c in changes]

# 3. Fail the release when the declared bump disagrees

# gate.py — CI refuses a version that understates its own diff.
import sys


def gate(declared: str, previous: str, changes: list[dict]) -> None:
    required = classify(changes)
    order = {"PATCH": 0, "MINOR": 1, "MAJOR": 2}
    actual = bump_kind(previous, declared)     # from the two version strings
    if order[actual] < order[required]:
        print(f"BLOCKED: declared {actual}, diff requires {required}", file=sys.stderr)
        for reason in justify(changes):
            print(f"  - {reason}", file=sys.stderr)
        raise SystemExit(1)
    print(f"{actual} bump is consistent with the diff ({required} required)")

Verify the gate blocks an understated bump, which is the case it exists for:

curl -sS "$CONTRACT_API/products/$PRODUCT/versions/latest" > /tmp/old.json
python3 gate.py --old /tmp/old.json --new "$CANDIDATE" --declared v1.3.0
# A CRS change declared as MINOR must exit 1 and name the clause.

# 4. Publish the diff alongside the version

A consumer facing a MAJOR bump needs the list of what changed, not the instruction to migrate.

python3 contract_diff.py /tmp/old.json "$CANDIDATE" \
  | jq '{from: env.PREVIOUS, to: env.DECLARED, changes: .}' \
  | curl -sS -X PUT "$CONTRACT_API/products/$PRODUCT/versions/$DECLARED/diff" \
         -H 'content-type: application/json' -d @-

# Configuration Reference

# Common Failure Modes & Fixes

A rename classifies as two unrelated changes. Root cause: correct, and deliberately so. A structural diff cannot know a rename was intended, and treating it as benign would let a field vanish under a MINOR bump. Fix: none needed — the MAJOR classification is right.

An “equivalent” CRS change is flagged. Root cause: also correct. EPSG:4326 and CRS84 differ in declared axis order, and consumers that trusted one will misread the other. Fix: accept the MAJOR, or leave the CRS alone.

A precision reduction passes as PATCH. Root cause: coordinate_precision absent from the contract, so the diff cannot see it. Fix: make it a required contract field; an unstated precision is a clause consumers depend on and nobody wrote down.

The gate blocks a change everyone agrees is safe. Root cause: usually a genuinely additive change to a field no consumer uses — which the diff cannot know. Fix: consumer-driven contract tests, which can demonstrate that no registered consumer breaks; that evidence, not an assertion, is what should override the classification.

The diff is empty and consumers still broke. Root cause: a behaviour change outside the contract — feature ordering, empty-result semantics, response size limits. Fix: add the negative clauses to the contract so they are diffable; a behaviour nobody declared is a behaviour nobody can version.

# FAQ

# Related

• Data Contracts for Spatial Products — the parent topic and what belongs in a contract
• Versioning Spatial Data Contracts with SemVer — the promotion path this gate sits in
• Deprecating a Spatial Data Product Safely — what a MAJOR bump obliges the producer to do