DEV Community

Ashley T
Ashley T

Posted on

Protocol Buffers for Server-Driven UI: A Practical Guide

#discuss #android #ios

Why Protobuf for SDUI?

Server-Driven UI (SDUI) systems rely on a backend sending a tree of UI components that the client renders dynamically. Most implementations use JSON as the transport format. While JSON is human-readable and flexible, it comes with performance costs that matter in mobile environments: verbose payloads, ambiguous types, and expensive parsing.

Protocol Buffers (Protobuf) offers a strongly-typed, binary-serialized alternative that dramatically reduces payload size and parsing time — both critical for SDUI, where every screen load depends on downloading and processing a component tree.

This document presents a proven approach to adopting Protobuf for SDUI, including schema design, migration strategies, and real benchmark data.

Key Advantages

1. Dramatically Smaller Payloads

Metric JSON Protobuf Improvement
Payload size (small screen) 2,501 bytes 593 bytes 76% smaller
Projected size (~30 components) ~12–18 KB ~3–4 KB ~75–80% smaller

On unstable 3G/4G connections, smaller payloads mean fewer retransmissions and faster time-to-render.

2. Faster Parsing

Metric JSON Protobuf Improvement
Full pipeline (parse + domain mapping) 0.0433 ms 0.0249 ms 1.7x faster
Projected (~30 components) ~8–15 ms ~1–2 ms ~85–90% faster

Protobuf achieves this through:

  • No intermediate tree: Streaming parse directly into typed objects
  • Integer field IDs: No string key comparisons
  • Zero ambiguity: Type resolved by field number, not discriminator strings
  • Reduced allocations: No JsonObject, JsonArray, or JsonPrimitive intermediaries

3. Compile-Time Type Safety

The oneof construct gives you polymorphic dispatch without runtime string matching. The compiler guarantees every component type is handled — missing a case is a build error, not a runtime crash.

4. Built-In Backward Compatibility

Protobuf's wire format is designed for evolution:

  • Adding a component: New field in oneof with a new field number. Old clients silently ignore it.
  • Adding a field to a component: New field number, default value used by old clients.
  • Removing a field: Mark as reserved. Never reuse field numbers.

No versioned endpoints, no breaking changes, no coordinated deploys.

5. Multi-Platform from a Single Schema

One .proto file generates native types for every platform:

protoc --java_out=lite:. sdui.proto        # Android
protoc --swift_out=. sdui.proto            # iOS
npx buf generate sdui.proto                # Web (TypeScript)
protoc --python_out=. sdui.proto           # Backend tooling
Enter fullscreen mode Exit fullscreen mode

Every team works with idiomatic, generated types — no manual model classes, no drift between platforms.

Schema Design for SDUI

The Polymorphism Challenge

SDUI's core challenge is representing heterogeneous lists of components. In JSON, a discriminator field like "component": "button" handles this. In Protobuf, the oneof construct provides type-safe polymorphism:

syntax = "proto3";
package sdui.v1;

message SDUIContent {
  string flow = 1;
  repeated SDUIScreen screens = 2;
  SDUIConfig config = 3;
  map<string, string> initial_state = 4;
}

message SDUIScreen {
  string id = 1;
  string title = 2;
  SDUIHeadButton button = 3;
  repeated SDUIComponent components = 4;
}

message SDUIComponent {
  string name = 1;
  string show_if = 2;

  oneof component {
    SDUIText text = 10;
    SDUIButton button = 11;
    SDUIInput input = 12;
    SDUIContainer container = 13;
    SDUIToggle toggle = 14;
    SDUIDropDown drop_down = 15;
    SDUIRadio radio = 16;
    SDUICheckbox checkbox = 17;
    SDUIAlert alert = 18;
    SDUIImage image = 19;
    SDUIBanner banner = 20;
  }
}
Enter fullscreen mode Exit fullscreen mode

Design Decisions

Decision Rationale
oneof component for polymorphism Compile-time type safety; no ambiguous parsing
repeated SDUIComponent children in Container Enables recursive nesting (tree structure)
map<string, string> for initial_state Simple representation for dynamic key-value state
Field numbers ≥ 10 for oneof components Reserves 1–9 for future common fields
Lite runtime on mobile Smaller binary footprint (~300 KB vs full runtime)

Adopting Protobuf: Regardless of Your Architecture

Whether you have a monolith, microservices, or a BFF layer, Protobuf can be adopted incrementally. Here are three strategies, from lowest effort to highest benefit.

Strategy 1: Translation Layer (Zero Backend Changes)

If your backend already serves JSON, add a lightweight translation service between your backend and clients:

┌──────────────┐  JSON  ┌─────────────────┐  Protobuf  ┌──────────┐
│ Your Backend │───────▶│ Translation BFF│────────────▶│ Clients  │
│ (unchanged)  │        │                 │             │          │
└──────────────┘        └─────────────────┘             └──────────┘
Enter fullscreen mode Exit fullscreen mode

The translation layer:

  • Receives JSON from your existing backend
  • Converts to Protobuf binary using JsonFormat.parser().ignoringUnknownFields()
  • Serves binary protobuf to clients

Key benefit: ignoringUnknownFields() means your backend can evolve freely. New JSON fields not yet in the .proto schema are silently ignored — no breaking changes.

// Example: Ktor translation endpoint
post("/translate") {
    val jsonBody = call.receiveText()
    val builder = SDUIContent.newBuilder()
    JsonFormat.parser().ignoringUnknownFields().merge(jsonBody, builder)
    val proto = builder.build()
    call.respondBytes(proto.toByteArray(), ContentType("application", "x-protobuf"))
}
Enter fullscreen mode Exit fullscreen mode

When to use: You want performance gains on the client without touching the backend. Ideal for legacy systems or when backend changes require long approval cycles.

Strategy 2: Dual Format with Content Negotiation

Serve both formats from the same endpoint using the Accept header:

GET /v1/screens/{screenId}
Accept: application/x-protobuf  → binary protobuf (new clients)
Accept: application/json        → JSON (legacy clients)
(no Accept header)              → binary protobuf (default)
Enter fullscreen mode Exit fullscreen mode

When to use: You're migrating clients incrementally. New app versions use Protobuf; older versions still get JSON. No forced upgrades, no coordinated releases.

Strategy 3: Native Protobuf Backend

The backend generates Protobuf directly. Maximum performance, no translation overhead:

┌──────────────┐  Protobuf  ┌──────────┐
│ Your Backend │───────────▶│ Clients  │
│              │            │          │
└──────────────┘            └──────────┘
Enter fullscreen mode Exit fullscreen mode

When to use: Greenfield SDUI systems, or after the translation layer has proven the approach and you're ready to go all-in.

Client Integration

Android (Kotlin)

Gradle setup:

plugins {
    id("com.google.protobuf") version "0.9.4"
}

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:3.25.2"
    }
    generateProtoTasks {
        all().forEach { task ->
            task.builtins {
                create("java") {
                    option("lite") // Use lite runtime for mobile
                }
            }
        }
    }
}

dependencies {
    implementation("com.google.protobuf:protobuf-javalite:3.25.2")
    implementation("com.squareup.retrofit2:converter-protobuf:2.9.0")
}
Enter fullscreen mode Exit fullscreen mode

Retrofit API:

interface SDUIApi {
    @GET("screens/{screenId}")
    suspend fun getScreen(
        @Path("screenId") screenId: String,
        @Header("Accept") accept: String = "application/x-protobuf",
    ): SDUIContent
}
Enter fullscreen mode Exit fullscreen mode

Retrofit's ProtoConverterFactory handles deserialization automatically.

Mapping to your domain layer:

// Proto → Domain mapping preserves your existing rendering pipeline
fun SDUIContent.toDomain(): ScreenContent =
    ScreenContent(
        flow = flow,
        screens = screensList.map { it.toDomain() },
        config = if (hasConfig()) config.toDomain() else null,
        initialState = initialStateMap.toMutableMap(),
    )

// Polymorphic dispatch via oneof — replaces JSON discriminator logic
fun SDUIComponent.toRenderable(): Renderable? =
    when (componentCase) {
        SDUIComponent.ComponentCase.CONTAINER -> ContainerComponent(container.toDomain())
        SDUIComponent.ComponentCase.BUTTON -> ButtonComponent(button.toDomain())
        SDUIComponent.ComponentCase.TEXT -> TextComponent(text.toDomain())
        // ... other components
        SDUIComponent.ComponentCase.COMPONENT_NOT_SET, null -> null
    }
Enter fullscreen mode Exit fullscreen mode

iOS (Swift) 

import SwiftProtobuf

let url = URL(string: "https://api.example.com/screens/home")!
let data = try await URLSession.shared.data(from: url).0
let content = try Sdui_V1_SDUIContent(serializedBytes: data)
Enter fullscreen mode Exit fullscreen mode

Web (TypeScript) 

import { SDUIContent } from './generated/sdui_pb';

const response = await fetch('/screens/home', {
    headers: { 'Accept': 'application/x-protobuf' }
});
const bytes = new Uint8Array(await response.arrayBuffer());
const content = SDUIContent.fromBinary(bytes);
Enter fullscreen mode Exit fullscreen mode

Schema Distribution

Clients need access to .proto files for code generation. Options:

Approach Complexity Best For
Serve via HTTP (GET /proto/sdui.proto) Low Small teams, rapid iteration
Git submodule Medium Multiple repos, version pinning
Package registry (Maven/npm/CocoaPods) Medium Published artifacts with versioning
Buf Schema Registry (BSR) High Large orgs, breaking change detection

A simple HTTP endpoint works well to start:

# Any platform can download and generate
curl -o sdui.proto https://api.example.com/proto/sdui.proto
protoc --swift_out=. sdui.proto
Enter fullscreen mode Exit fullscreen mode

CI/CD Integration

Build Impact

Aspect Impact Mitigation
Build time +5–10s for generateProto Incremental — only runs when .proto changes
App size +300–400 KB (protobuf-lite) Smaller than JSON libraries; offset by network savings
Build cache Proto generation is cacheable Gradle/Bazel build cache handles this
CI pipeline New validation step buf lint + buf breaking

Recommended CI Pipeline 

Source → Proto Lint (buf) → Generate Code → Compile + Tests → Static Analysis
                ↓
         Breaking Change Check (buf breaking --against main)
Enter fullscreen mode Exit fullscreen mode

The buf breaking step prevents accidental backward-incompatible changes from reaching production.

Debugging & Developer Experience

Binary formats are harder to inspect than JSON. Here's how to maintain good DX:

Tool Use Case
/json debug endpoint Human-readable view of the same data
Charles Proxy / Proxyman Auto-decode if .proto file is registered
protoc --decode CLI-based decode of captured binary
Logging interceptor (debug builds) Decoded payload in logcat/console

Learning Curve

Topic Difficulty
Basic .proto syntax Low
oneof, repeated, map Medium
Gradle/build tool setup Medium
Binary debugging High (mitigated by tooling above)
Schema evolution rules Medium

Risks and Mitigations

Risk Impact Mitigation
Team learning curve Medium Pair programming, documentation, gradual rollout
Production debugging High Dual endpoints; decoded logging in debug builds
Field number conflicts High buf breaking in CI; code review discipline
App size increase Low Protobuf-lite adds ~300 KB
Tooling compatibility Medium Custom interceptors for observability platforms

Getting Started in 30 Minutes

  1. Define your schema: Write a .proto file modeling your SDUI component tree using oneof for polymorphism.

  2. Generate client code: Use protoc (or Buf) to generate types for your platform.

  3. Add a translation endpoint: If you already have a JSON backend, add a single endpoint that converts JSON → Protobuf using JsonFormat.parser().ignoringUnknownFields().

  4. Update your client: Replace your JSON deserialization with Protobuf deserialization. Map to your existing domain models — your rendering layer doesn't need to change.

  5. Measure: Compare payload sizes and parse times. The numbers speak for themselves.

Conclusion

Protobuf is not just a serialization format — for SDUI, it's an architecture upgrade:

  • 76% smaller payloads mean faster screen loads on any network
  • 1.7x faster parsing means smoother transitions between screens
  • Compile-time type safety means fewer runtime crashes from malformed responses
  • Built-in versioning means no coordinated deploys when adding components
  • Single schema, every platform means no drift between Android, iOS, and Web

The migration doesn't require a rewrite. Start with a translation layer, prove the gains, then go native. Your rendering pipeline stays the same — only the transport changes.

Top comments (0)