Implementing authoritative spatial data pipelines requires moving beyond read-only visualization into bidirectional data exchange. This page covers production-grade patterns for creating, updating, and deleting geospatial features via OGC Web Feature Service – Transactional (WFS-T) endpoints. The intended audience is GIS platform engineers, Python backend developers, and government agency technical teams who need synchronized, versioned, and auditable spatial datasets across distributed infrastructure.
Unlike static shapefile distributions or cached tile layers, WFS-T enables direct feature-level manipulation over HTTP. This capability sits at the core of the OGC Standards Architecture & Service Fundamentals service contract model, where interoperability, schema validation, and transactional integrity dictate system reliability. While read-only protocols excel at rendering, transactional services demand strict adherence to XML payload structures, coordinate reference system alignment, and database-level isolation guarantees.
Before implementing transactional workflows, satisfy these baseline requirements. Deviating from them typically produces InvalidParameterValue or OperationProcessingFailed exceptions at runtime — with limited diagnostic context from the server.
Stack dependencies:
READ COMMITTED or SERIALIZABLE isolation. WFS-T maps directly to SQL INSERT, UPDATE, and DELETE; without proper indexing, concurrent edits trigger deadlocks or phantom reads.wfs:Transaction appears in the OperationsMetadata section of the GetCapabilities response before routing production traffic.requests, lxml, and pyproj installed.srsName, and geometry element names differ between versions.Version selection affects every downstream detail. The WFS 2.0 vs 1.1.0 Breaking Changes for Backend Devs guide covers namespace shifts, mandatory handle attributes, and response envelope restructuring in detail. If your stack mixes versions — a common pattern when legacy desktop GIS clients send WFS 1.1.0 while a Python pipeline sends WFS 2.0 — read that guide before writing a single line of transaction code.
Coordinate reference system alignment is the single largest source of silent data corruption in WFS-T deployments. The SRS and Coordinate Reference System Handling guide covers on-the-fly reprojection risks and the axis-order inversion that catches most teams on their first EPSG:4326 insert.
The diagram below shows the full lifecycle of a WFS-T write operation from client to database, highlighting the validation checkpoints where failures most commonly occur.
Every WFS-T write is wrapped in a <wfs:Transaction> element. The handle attribute (a client-assigned string) is mandatory for idempotency tracking — if a network timeout occurs before the response arrives, resubmitting the identical handle allows a compliant server to return the cached result without re-executing the mutation.
<wfs:Transaction service="WFS" version="2.0.0" handle="txn-2024-08-15-001"
xmlns:wfs="http://www.opengis.net/wfs/2.0"
xmlns:fes="http://www.opengis.net/fes/2.0"
xmlns:gml="http://www.opengis.net/gml/3.2">
<!-- Insert / Update / Delete operations go here -->
</wfs:Transaction>
For WFS 1.1.0, replace the wfs namespace URI with http://www.opengis.net/wfs and fes with http://www.opengis.net/ogc. The envelope structure is otherwise identical.
Insert — Provide complete feature geometry and all mandatory attributes. The server maps each child element to a database column; missing NOT NULL columns produce an OperationProcessingFailed exception with no row written:
<wfs:Insert handle="op-insert-01">
<ns:RoadSegment xmlns:ns="http://example.com/roads">
<ns:name>Main Street</ns:name>
<ns:road_class>primary</ns:road_class>
<ns:geom>
<gml:LineString srsName="urn:ogc:def:crs:EPSG::4326" srsDimension="2">
<gml:posList>51.501 -0.142 51.502 -0.140</gml:posList>
</gml:LineString>
</ns:geom>
</ns:RoadSegment>
</wfs:Insert>
Note the axis order: urn:ogc:def:crs:EPSG::4326 mandates latitude first, longitude second. This is the most common source of silent topology corruption — features appear in the correct database row but are mirrored across the prime meridian or equator.
Update — Use <wfs:Property> elements to target specific attributes. Omit unchanged fields entirely to reduce payload size. Scope the filter tightly: an unscoped <wfs:Update> without a <fes:Filter> updates every row in the feature type:
<wfs:Update typeName="ns:RoadSegment">
<wfs:Property>
<wfs:ValueReference>ns:road_class</wfs:ValueReference>
<wfs:Value>secondary</wfs:Value>
</wfs:Property>
<fes:Filter>
<fes:ResourceId rid="RoadSegment.1234"/>
</fes:Filter>
</wfs:Update>
Delete — Always include a <fes:Filter> (WFS 2.0) or <ogc:Filter> (WFS 1.1.0). A <wfs:Delete> without a filter is equivalent to DELETE FROM table — some servers reject it, others execute it:
<wfs:Delete typeName="ns:RoadSegment">
<fes:Filter>
<fes:ResourceId rid="RoadSegment.1234"/>
</fes:Filter>
</wfs:Delete>
| Aspect | WFS 1.1.0 | WFS 2.0 |
|---|---|---|
| WFS namespace | http://www.opengis.net/wfs |
http://www.opengis.net/wfs/2.0 |
| Filter namespace | http://www.opengis.net/ogc |
http://www.opengis.net/fes/2.0 |
| GML version | GML 3.1.1 | GML 3.2.1 |
| Feature ID element | ogc:FeatureId fid= |
fes:ResourceId rid= |
| Default CRS axis order | lon/lat (OGC legacy) | authority-defined (EPSG: lat/lon for 4326) |
| Locking | LockFeature + GetFeatureWithLock |
Optional; implementation-defined |
| Response element | wfs:WFS_TransactionResponse |
wfs:TransactionResponse |
| totalInserted location | wfs:InsertResults count |
wfs:TransactionSummary/wfs:totalInserted |
A successful WFS 2.0 insert returns:
<wfs:TransactionResponse xmlns:wfs="http://www.opengis.net/wfs/2.0"
xmlns:fes="http://www.opengis.net/fes/2.0">
<wfs:TransactionSummary>
<wfs:totalInserted>1</wfs:totalInserted>
<wfs:totalUpdated>0</wfs:totalUpdated>
<wfs:totalDeleted>0</wfs:totalDeleted>
</wfs:TransactionSummary>
<wfs:InsertResults>
<wfs:Feature handle="op-insert-01">
<fes:ResourceId rid="RoadSegment.5678"/>
</wfs:Feature>
</wfs:InsertResults>
</wfs:TransactionResponse>
WFS-T does not guarantee atomicity across mixed operation types unless the server explicitly documents it. Parse TransactionSummary counts programmatically and implement compensating transactions whenever the totals do not match your expected batch size.
The following module is production-ready for Python 3.10+. It posts a WFS-T transaction, parses the response, and returns structured results. It handles both WFS 1.1.0 and 2.0 response envelopes.
"""wfs_transaction.py — production WFS-T client for Python 3.10+
Dependencies: pip install requests lxml
"""
from __future__ import annotations
import time
import random
import logging
from dataclasses import dataclass, field
from typing import Literal
import requests
from lxml import etree
logger = logging.getLogger(__name__)
# Namespace maps keyed by WFS version string
_NS: dict[str, dict[str, str]] = {
"2.0.0": {
"wfs": "http://www.opengis.net/wfs/2.0",
"fes": "http://www.opengis.net/fes/2.0",
"ows": "http://www.opengis.net/ows/1.1",
},
"1.1.0": {
"wfs": "http://www.opengis.net/wfs",
"fes": "http://www.opengis.net/ogc", # OGC Filter Encoding 1.1
"ows": "http://www.opengis.net/ows",
},
}
@dataclass
class TransactionResult:
total_inserted: int = 0
total_updated: int = 0
total_deleted: int = 0
inserted_ids: list[str] = field(default_factory=list)
raw_xml: bytes = field(default=b"", repr=False)
def execute_wfs_transaction(
endpoint: str,
xml_payload: str,
auth_headers: dict[str, str],
*,
version: Literal["2.0.0", "1.1.0"] = "2.0.0",
timeout: int = 30,
max_retries: int = 3,
) -> TransactionResult:
"""Post a WFS-T transaction and parse the response.
Args:
endpoint: Full WFS endpoint URL (no query-string parameters needed;
the service and version are embedded in the XML body).
xml_payload: Complete <wfs:Transaction> XML string, UTF-8 encoded.
auth_headers: Dict of HTTP headers for authentication (Bearer tokens,
API keys, or basic-auth via requests.auth).
version: WFS version string controlling namespace resolution.
timeout: Per-attempt HTTP timeout in seconds.
max_retries: Number of retry attempts for 5xx responses.
Returns:
TransactionResult dataclass with counts and inserted feature IDs.
Raises:
requests.HTTPError: on non-retryable 4xx responses.
RuntimeError: if all retry attempts are exhausted.
"""
ns = _NS[version]
headers = {
"Content-Type": "application/xml; charset=utf-8",
**auth_headers,
}
payload_bytes = xml_payload.encode("utf-8")
for attempt in range(1, max_retries + 1):
try:
resp = requests.post(
endpoint,
data=payload_bytes,
headers=headers,
timeout=timeout,
)
# 4xx errors are not retried — fix the payload, not the timing
if 400 <= resp.status_code < 500:
resp.raise_for_status()
if resp.status_code >= 500:
if attempt == max_retries:
resp.raise_for_status()
_backoff(attempt)
continue
return _parse_response(resp.content, ns)
except requests.Timeout:
logger.warning("WFS-T attempt %d timed out", attempt)
if attempt == max_retries:
raise RuntimeError(f"WFS-T transaction failed after {max_retries} attempts")
_backoff(attempt)
raise RuntimeError("Unreachable")
def _backoff(attempt: int) -> None:
"""Jittered exponential backoff: 2^attempt seconds ± 20% jitter."""
base = 2 ** attempt
sleep_s = base * (0.8 + 0.4 * random.random())
logger.info("Retry in %.1fs", sleep_s)
time.sleep(sleep_s)
def _parse_response(content: bytes, ns: dict[str, str]) -> TransactionResult:
"""Extract TransactionSummary counts and InsertResults IDs from the response."""
root = etree.fromstring(content) # raises XMLSyntaxError if server returns HTML error page
# Check for OWS ServiceException (returned as 200 OK by many WFS servers)
exc_el = root.find(".//ows:ExceptionText", ns)
if exc_el is not None:
raise RuntimeError(f"WFS ServiceException: {exc_el.text!r}")
def _count(tag: str) -> int:
el = root.find(f".//wfs:{tag}", ns)
return int(el.text) if el is not None and el.text else 0
# ResourceId/@rid under InsertResults — WFS 2.0 uses fes:ResourceId
# WFS 1.1.0 uses fes:FeatureId/@fid (same namespace alias, different element/attr)
rid_elements = root.findall(".//fes:ResourceId", ns)
fid_elements = root.findall(".//fes:FeatureId", ns) # 1.1.0 fallback
inserted_ids = (
[el.get("rid") for el in rid_elements]
if rid_elements
else [el.get("fid") for el in fid_elements]
)
return TransactionResult(
total_inserted=_count("totalInserted"),
total_updated=_count("totalUpdated"),
total_deleted=_count("totalDeleted"),
inserted_ids=[i for i in inserted_ids if i],
raw_xml=content,
)
Namespace resolution by version. The _NS dict maps WFS version strings to their correct namespace URIs. WFS 2.0 uses http://www.opengis.net/wfs/2.0 and http://www.opengis.net/fes/2.0; WFS 1.1.0 uses the bare http://www.opengis.net/wfs and http://www.opengis.net/ogc. Mixing these causes every root.find() call to return None silently, making the response appear empty.
Retry logic with jittered backoff. Only 5xx and Timeout errors are retried. A 400 InvalidParameterValue or 403 Forbidden means the payload or credentials are wrong — retrying is pointless and wastes server resources. The _backoff function adds ±20% jitter to the exponential base to prevent thundering herd scenarios during database recovery windows.
OWS ServiceException detection. Many WFS servers return error details inside a 200 OK XML response rather than a proper HTTP error status. The _parse_response function checks for ows:ExceptionText before attempting to read summary counts — this catches the OperationProcessingFailed responses that raise_for_status() would silently pass.
ResourceId vs FeatureId. WFS 2.0 uses fes:ResourceId/@rid; WFS 1.1.0 uses ogc:FeatureId/@fid. The parser tries the 2.0 form first and falls back to the 1.1.0 form, so the same function works against both server versions without conditional branching in the caller.
| Exception Code | Typical Cause | Fix |
|---|---|---|
InvalidParameterValue |
Malformed srsName, unknown typeName, or unsupported version |
Validate namespace and feature type name against GetCapabilities |
OperationProcessingFailed |
NOT NULL constraint, geometry type mismatch, or topology error | Enable verbose exceptions in GeoServer; check column constraints in PostGIS |
InvalidValue |
Attribute value violates domain constraint or data type | Validate against DescribeFeatureType XSD before submitting |
MissingParameterValue |
Required <wfs:Property> element absent from Update |
Audit payload against feature type schema |
NoApplicableCode |
Generic server error; check server logs | Enable EXCEPTIONS=application/vnd.ogc.se_xml for detail |
The SRS and Coordinate Reference System Handling guide documents this in full, but the WFS-T-specific trap is worth calling out: GML 3.2 posList uses the axis order defined by the srsName URI, not by the order you intuitively expect. For urn:ogc:def:crs:EPSG::4326, posList must be lat lon pairs. If you write lon lat, features will be inserted into the database at geographically valid but completely wrong locations — PostGIS accepts the coordinates without error.
Use pyproj.CRS.from_user_input("EPSG:4326").axis_info to programmatically confirm axis order before encoding coordinates:
from pyproj import CRS
crs = CRS.from_user_input("EPSG:4326")
axis_names = [a.name for a in crs.axis_info]
# Returns: ['Latitude', 'Longitude'] — confirming lat-lon order for GML 3.2
A <wfs:Delete> or <wfs:Update> with no <fes:Filter> child operates on the entire feature type. GeoServer 2.24+ rejects such requests by default; older versions and some alternative servers execute them silently. Always assert a filter element is present in your payload construction code:
def build_delete_payload(type_name: str, resource_id: str, handle: str) -> str:
assert resource_id, "resource_id must be non-empty to prevent full-table delete"
return f"""
<wfs:Transaction service="WFS" version="2.0.0" handle="{handle}"
xmlns:wfs="http://www.opengis.net/wfs/2.0"
xmlns:fes="http://www.opengis.net/fes/2.0">
<wfs:Delete typeName="{type_name}">
<fes:Filter><fes:ResourceId rid="{resource_id}"/></fes:Filter>
</wfs:Delete>
</wfs:Transaction>""".strip()
"""test_wfs_transaction.py"""
import pytest
from unittest.mock import MagicMock, patch
from wfs_transaction import execute_wfs_transaction, TransactionResult
MOCK_RESPONSE_200 = b"""
<wfs:TransactionResponse xmlns:wfs="http://www.opengis.net/wfs/2.0"
xmlns:fes="http://www.opengis.net/fes/2.0">
<wfs:TransactionSummary>
<wfs:totalInserted>1</wfs:totalInserted>
<wfs:totalUpdated>0</wfs:totalUpdated>
<wfs:totalDeleted>0</wfs:totalDeleted>
</wfs:TransactionSummary>
<wfs:InsertResults>
<wfs:Feature handle="op-01"><fes:ResourceId rid="Layer.99"/></wfs:Feature>
</wfs:InsertResults>
</wfs:TransactionResponse>
"""
MOCK_SERVICE_EXCEPTION = b"""
<ows:ExceptionReport xmlns:ows="http://www.opengis.net/ows/1.1">
<ows:Exception exceptionCode="OperationProcessingFailed">
<ows:ExceptionText>Feature type not found: ns:BadType</ows:ExceptionText>
</ows:Exception>
</ows:ExceptionReport>
"""
@patch("wfs_transaction.requests.post")
def test_successful_insert(mock_post: MagicMock) -> None:
mock_resp = MagicMock(status_code=200, content=MOCK_RESPONSE_200)
mock_resp.raise_for_status = lambda: None
mock_post.return_value = mock_resp
result = execute_wfs_transaction(
"http://geoserver/wfs", "<wfs:Transaction/>", {}, version="2.0.0"
)
assert result.total_inserted == 1
assert result.inserted_ids == ["Layer.99"]
@patch("wfs_transaction.requests.post")
def test_service_exception_raises(mock_post: MagicMock) -> None:
mock_resp = MagicMock(status_code=200, content=MOCK_SERVICE_EXCEPTION)
mock_resp.raise_for_status = lambda: None
mock_post.return_value = mock_resp
with pytest.raises(RuntimeError, match="ServiceException"):
execute_wfs_transaction("http://geoserver/wfs", "<wfs:Transaction/>", {})
@patch("wfs_transaction.requests.post")
def test_retries_on_500(mock_post: MagicMock) -> None:
mock_500 = MagicMock(status_code=500)
mock_500.raise_for_status.side_effect = Exception("Server error")
mock_ok = MagicMock(status_code=200, content=MOCK_RESPONSE_200)
mock_ok.raise_for_status = lambda: None
mock_post.side_effect = [mock_500, mock_ok]
with patch("wfs_transaction.time.sleep"): # skip actual sleep in tests
result = execute_wfs_transaction(
"http://geoserver/wfs", "<wfs:Transaction/>", {}, max_retries=2
)
assert result.total_inserted == 1
The OGC CITE test suite includes a WFS 2.0 conformance class that exercises transactional operations. To run it locally against a GeoServer instance:
# Pull the CITE test engine (requires Java 11+)
docker pull ogccite/ets-wfs20
docker run --rm -p 8080:8080 ogccite/ets-wfs20
# Then submit your GeoServer WFS endpoint via the CITE web UI at http://localhost:8080/teamengine
# Select: WFS 2.0 → Transaction conformance class → enter endpoint URL
After running CITE, inspect the wfs:Transaction test results specifically. Common failures in the transactional class: missing handle attribute support, incorrect InsertResults structure, and non-atomic rollback on constraint violations.
GML is verbose. A single feature with a complex polygon geometry can produce 50–200 KB of XML. Batching 200 such features into one transaction produces a 10–40 MB payload that strains both the HTTP server’s request buffer and the XML parser’s memory. Empirically, batches of 50–150 features per transaction give the best throughput for complex geometries; simpler point features tolerate batches of 500–1000.
For very large ingestion jobs (millions of features), prefer streaming parsers over loading the entire response into memory:
import requests
from lxml import etree
def stream_transaction_response(endpoint: str, payload: bytes, headers: dict) -> list[str]:
"""Stream-parse InsertResults to avoid loading large responses into RAM."""
with requests.post(endpoint, data=payload, headers=headers, stream=True, timeout=120) as resp:
resp.raise_for_status()
context = etree.iterparse(resp.raw, events=("end",), tag="{http://www.opengis.net/fes/2.0}ResourceId")
ids = [el.get("rid") for _, el in context if el.get("rid")]
return ids
Reuse HTTP connections across multiple transactions with a requests.Session object. GeoServer maintains a JDBC connection pool; per-transaction TCP handshakes become the bottleneck at high throughput:
import requests
session = requests.Session()
session.headers.update({"Content-Type": "application/xml; charset=utf-8"})
session.headers.update(auth_headers)
# Reuse session across all transactions in a batch job
for batch in batches:
resp = session.post(endpoint, data=batch.encode("utf-8"), timeout=60)
resp.raise_for_status()
Tile caches introduce staleness for transactionally updated datasets. As explained in WMTS Tile Matrix Sets Explained, each zoom level may cache independently. After a successful wfs:Transaction, invalidate the affected tile ranges via GeoWebCache’s REST API:
import requests
def invalidate_gwc_tiles(gwc_url: str, layer: str, bbox: list[float], auth: tuple) -> None:
"""Trigger GeoWebCache seed/truncate for the bounding box affected by a WFS-T write."""
payload = {
"seedRequest": {
"name": layer,
"bounds": {"coords": {"double": bbox}},
"srs": {"number": 4326},
"zoomStart": 0,
"zoomStop": 18,
"type": "truncate",
"threadCount": 2,
}
}
resp = requests.post(
f"{gwc_url}/rest/seed/{layer}.json",
json=payload,
auth=auth,
timeout=15,
)
resp.raise_for_status()
Route GetFeature and DescribeFeatureType requests to read replicas or tile caches while directing wfs:Transaction calls exclusively to the primary database node. This mirrors the architectural pattern described in Understanding OGC Web Map Service Specifications where rendering pipelines are decoupled from authoritative data sources. In GeoServer, configure a separate virtual service with wfs.transactional=true only on the primary-backed service definition.
Not universally. WFS 2.0 leaves atomicity implementation-defined. GeoServer commits all operations in a single transaction atomically by default; other servers may partially commit. Always parse the TransactionSummary counts and implement compensating transactions whenever totalInserted + totalUpdated + totalDeleted does not equal your expected batch size.
WFS 2.0 with GML 3.2 uses the axis order defined by the CRS authority. urn:ogc:def:crs:EPSG::4326 is latitude-longitude — not longitude-latitude. Encode posList coordinates as lat lon pairs. Use the legacy HTTP URI form http://www.opengis.net/gml/srs/epsg.xml#4326 only when explicitly targeting a WFS 1.1.0 server that requires longitude-first ordering.
WFS 1.1.0 provides LockFeature and GetFeatureWithLock operations for pessimistic concurrency. WFS 2.0 does not mandate locking but supports optimistic concurrency via application-level timestamps or gml:validTime. For multi-tenant government deployments, implement a checkout/check-in workflow outside the WFS protocol layer, using a versioning table in PostGIS to serialise conflicting edits.
The most common causes: missing NOT NULL columns in the GML feature payload; geometry type mismatch (sending a MultiPolygon into a Polygon column); SRS mismatch between the incoming geometry’s srsName and the feature type’s declared CRS; and exceeding the server’s maxFeatures or payload size limit. Enable GeoServer’s detailed exception mode with EXCEPTIONS=application/vnd.ogc.se_xml to surface the underlying database constraint message.
Yes, for high-throughput write pipelines. Server-side reprojection on inserts introduces subtle topology distortion for complex geometries and adds CPU overhead to every write. Enforce client-side projection validation with pyproj before submitting geometries, and configure GeoServer to reject mismatched SRS values rather than silently reproject. For the reprojection patterns themselves, see Handling Spatial Reference Mismatches in OGC Requests.
Back to OGC Standards Architecture & Service Fundamentals.
Related: