Geospatial gRPC Protocol Standard

An open, vendor-neutral gRPC/Protobuf protocol standard for geospatial systems: feature access, mobile data collection, styles, elevation, 3D scenes/tiles, and execution workflows (processes, pipelines, rendering, app building, deployment). Existing geospatial interop standards are REST/XML-first; this project defines the equivalent contracts as strongly typed, streaming-capable gRPC services so servers and clients in any language can interoperate over one schema.

This is a schema/contract repository — the .proto files under geospatial/v1/ are the source of truth. There is no server or application code here; implementations and SDKs generate clients from these definitions (ownership rules).

Status

Pre-1.0 (alpha). The wire contract is still being deliberately settled; alpha releases may include acknowledged breaking changes, each documented in the CHANGELOG and re-baselined with a new tag. From v1.0.0 the full within-major compatibility guarantees in VERSIONING.md apply without exception. Every PR is gated by buf lint, buf format, buf breaking (WIRE_JSON + RPC/service no-delete rules), multi-language codegen, and a conformance-fixture round-trip.

What the standard defines

All services live in the geospatial.v1 package, one service per file. Each execution-plane service follows a validate / dry-run / execute pattern.

Service	Purpose
FeatureService	Feature CRUD: query, server-streaming pages, batch edits
FormService	Mobile data collection: dynamic forms, validation, submission
WorkspaceService	Workspace lifecycle: create/open/list, promote, retain/release, quotas
ArtifactService	Artifact lifecycle: publish/read/inspect, retention policies
ProcessService	Geospatial process execution: plan validation, dry-run, sync/streaming/async
PipelineService	Data publishing pipelines: validation, dry-run, stage-by-stage execution
RenderService	Map composition; produces MapLibre-compatible MapPackage bundles
BuilderService	Application bundle synthesis; produces AppPackage bundles
DeploymentService	Promotion to live targets with health telemetry and rollback
SpecService	Declarative spec plan/apply workflows with streaming progress
StyleService	2D style catalog: StyleRef styles with typed encodings (MapLibre, SLD, Esri drawing info)
ElevationService	Point elevation and geodesic profile sampling
SceneService	3D scene catalog backed by 3D Tiles tilesets and optional terrain
TileService	3D tile delivery by node, or streamed by LOD and extent

Shared type modules: common.proto, spatial_types.proto (geometries with Z/M support), execution_types.proto (plans, steps, jobs, provenance, structured errors), packaging_types.proto (MapPackage, AppPackage, DeploymentSpec), workspace_artifact_types.proto (typed WorkspaceRef/ArtifactRef/RetentionPolicyRef handles and lifecycle enums), style_types.proto, and scene_types.proto.

The full capability map is in docs/features/README.md; message-level detail is in the protocol specification.

Quick start

Generate client code

git clone https://github.com/honua-io/geospatial-grpc.git
cd geospatial-grpc

# Install the Buf CLI (https://buf.build/docs/installation), e.g.:
npm install -g @bufbuild/buf

# Generate every configured language into gen/
buf generate
# gen/csharp, gen/go, gen/java, gen/python, gen/rust, gen/swift, gen/typescript

# Or generate a single language with its dedicated template
buf generate --template buf.gen.go.yaml --output generated/go
# also: buf.gen.csharp.yaml, buf.gen.python.yaml, buf.gen.javascript.yaml, buf.gen.java.yaml

gen/ is build output — it is never committed; regenerate it from the protos.

.NET: use the published protocol package

The Geospatial.Grpc NuGet package (netstandard2.0, protos compiled via Grpc.Tools) is published to GitHub Packages by the Publish .NET Protocol Package workflow on geospatial-grpc-v* tags. Downstream .NET projects should reference the package rather than copying .proto files. You can also pack it locally:

dotnet pack src/Geospatial.Grpc/Geospatial.Grpc.csproj --configuration Release -o ./nupkgs

First query

.NET:

using Geospatial.V1;
using Grpc.Net.Client;

using var channel = GrpcChannel.ForAddress("https://api.example.com");
var client = new FeatureService.FeatureServiceClient(channel);

var response = await client.QueryFeaturesAsync(new QueryFeaturesRequest
{
    ServiceId = "parcels",
    LayerId = 0,
    Where = "AREA > 1000",
    ReturnGeometry = true
});

foreach (var feature in response.Features)
{
    Console.WriteLine($"Feature {feature.Id}: {feature.Attributes}");
}

TypeScript (protobuf-es + Connect v2):

import { FeatureService } from './gen/typescript/geospatial/v1/feature_service_pb.js';
import { createClient } from '@connectrpc/connect';
import { createGrpcTransport } from '@connectrpc/connect-node';

const transport = createGrpcTransport({ baseUrl: 'https://api.example.com' });
const client = createClient(FeatureService, transport);

const response = await client.queryFeatures({
  serviceId: 'parcels',
  layerId: 0,
  where: 'AREA > 1000',
  returnGeometry: true,
});

response.features.forEach((feature) => {
  console.log(`Feature ${feature.id}:`, feature.attributes);
});

Python:

import grpc
from geospatial.v1 import feature_service_pb2
from geospatial.v1 import feature_service_pb2_grpc

channel = grpc.secure_channel('api.example.com:443', grpc.ssl_channel_credentials())
client = feature_service_pb2_grpc.FeatureServiceStub(channel)

response = client.QueryFeatures(feature_service_pb2.QueryFeaturesRequest(
    service_id='parcels',
    layer_id=0,
    where='AREA > 1000',
    return_geometry=True,
))
for feature in response.features:
    print(f'Feature {feature.id}: {feature.attributes}')

Runnable end-to-end samples live in examples/:

Example	Run
JavaScript/TypeScript	npm install && npm run generate && npm run dev
Python	pip install -r requirements.txt && python main.py
.NET	dotnet run

Conformance suite

conformance/ holds canonical request/response fixtures for the core workflows plus a language-agnostic regression harness that round-trips them against the live schema with buf convert — catching contract drift before it reaches generated SDKs:

conformance/run.sh            # verify fixtures against committed goldens
conformance/run.sh --update   # regenerate goldens after a reviewed schema change

Each schema release publishes the fixture set as a versioned, checksummed tarball on the matching GitHub Release (conformance-fixtures-<version>.tar.gz). Implementations pin a version with conformance/fetch-fixtures.sh --version <version> and run the bundled harness in their own CI. See conformance/README.md for the consumer contract.

Versioning and stability

VERSIONING.md is the canonical policy. In short:

• Proto package majors (geospatial.v1) align with release-tag majors.
• Within a major: wire compatibility, JSON mapping stability, field/enum number stability, and RPC surface stability are guaranteed between tagged releases.
• Breaking changes require deprecation first, maintainer sign-off, and a new package version path (geospatial/v2) — enforced in CI by buf breaking on every PR and on every push to trunk against the previous release tag.
• Pre-1.0 exception: while tags are v0.x-alpha, coordinated breaks are allowed under documented conditions (changelog acknowledgment + new baseline tag).

Implementing the standard

1. Generate server stubs for your language (buf generate, or the per-language templates).
2. Implement the services relevant to your product — the standard does not require every service.
3. Validate payload compatibility against the pinned conformance fixtures in your CI.
4. Follow CONTRIBUTING.md to propose schema changes — contracts evolve here first, never in downstream copies (proto ownership).

Known implementations and clients:

• Honua Server — reference server implementation (ELv2)
• Honua .NET SDK and Honua Mobile — .NET / MAUI clients
• Honua JS SDK — JavaScript/TypeScript clients
• Your implementation here — PRs welcome.

Documentation

Document	Contents
Protocol specification	Design principles and per-service protocol detail
Getting started	Tooling setup and per-language walkthroughs
Feature map	Implemented protocol surfaces and boundaries
Proto ownership	Canonical-source and downstream sync rules
Versioning policy	Compatibility guarantees and breaking-change governance
Release checklist	Release coordination and client regeneration
Changelog	Release history, including acknowledged alpha baselines

Related projects

• geospatial-mcp — companion open standard: geospatial tools over the Model Context Protocol
• geobench — vendor-neutral benchmark suite for geospatial servers

Contributing

Contributions are welcome — see CONTRIBUTING.md for local validation (buf lint, buf format --diff --exit-code, buf breaking --against '.git#branch=trunk'), the proto change workflow, and what must not change within v1. Questions and proposals go through GitHub Issues.

Security

Report vulnerabilities privately to security@honua.io — see the security policy. Do not open public issues for security reports.

License

Apache License 2.0.