gRPC has been open source for over a decade and has become an established, mature project used at pretty much every major tech company. That maturity also cements design decisions that don’t make sense anymore. Today, we’re going to discuss a hyper-specific case of that: service configs.

Service configs are JSON strings

gRPC is well-known for its heavy client design, where load balancing is built in. Here’s what it looks like to configure round-robin load balancing and a retry policy with a grpc-go client:

serviceConfig := `{
    "loadBalancingConfig": [
        { "round_robin": {} }
    ],
    "methodConfig": [{
        "name": [{"service": "my.service.v1.MyService"}],
        "retryPolicy": {
            "maxAttempts": 4,
            "initialBackoff": "0.1s",
            "maxBackoff": "1s",
            "backoffMultiplier": 2.0,
            "retryableStatusCodes": ["UNAVAILABLE"]
        }
    }]
}`
 
conn, err := grpc.NewClient(
    "dns:///my-service.default.svc.cluster.local:50051",
    grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})),
    grpc.WithDefaultServiceConfig(serviceConfig),
)

You might notice that serviceConfig is just a string literal with JSON in it. On app startup, grpc-go parses the string with encoding/json and ignores unknown fields. As a result, if you misspell "retryPolicy", grpc-go will continue on, silently ignoring your policy. As one user on the grpc-go issue tracker put it: “I can put anything in there and it’ll still compile, and still pass static analysis.”

What makes this frustrating is that gRPC already has a Protobuf schema for this exact config: service_config.proto. No gRPC project publishes Go code for it, though. The grpc-proto repository only has the .proto file, and grpc-go deleted its own generated copy from internal/proto/grpc_service_config way back in 2022.

If you want the sanity of static types, you can generate the Go types yourself, marshal the message with protojson.Marshal, and pass the resulting string to WithDefaultServiceConfig. Even that breaks on certain fields, though. Internally, grpc-go doesn’t actually use protojson to parse the string. Instead, it uses a custom encoding/json parser that doesn’t fully understand protojson. For example, it doesn’t support quoted numbers for uint64 fields. If you use protojson.Marshal to configure ring_hash_experimental (which uses uint64 for ring sizes), grpc-go v1.85.0 rejects the JSON that protojson just generated. PRs like #9271 aim to smooth over issues like this, but a more compatible parser still isn’t a typed API.

As you can tell, this article is mostly centered around Go, but it’s interesting to see that there are other languages that handle this differently:

  • grpc-java takes a Map<String, ?> instead of a string, which is only marginally better.
  • Node’s @grpc/grpc-js gives you TypeScript types (ServiceConfig, MethodConfig, RetryPolicy), but you still have to JSON.stringify the object before passing it in.
  • grpc-dotnet gives you a typed API for ServiceConfig.

Why service config uses JSON

The JSON string (and the word Default in WithDefaultServiceConfig) starts making sense once you look at where service config is expected to come from.

gRPC’s name resolution is pluggable. When you use a DNS scheme like dns:///my-service with the client, the client resolves the DNS name into one or more IP addresses. Along with the DNS request for the IP records, the resolver asks for a TXT record named _grpc_config.my-service whose value is grpc_config= followed by a JSON array of service config choices. WithDefaultServiceConfig was only intended to be a fallback when the resolver doesn’t return a config of its own.

In 2017, gRFC A2 spelled out how to ship service configs to open-source clients this way. A service owner can configure the retry and load-balancing settings next to the service’s DNS entries so that clients pick them up automatically. It’s a neat system, albeit probably a bit over-engineered.

The service config spec also explains why JSON is used here rather than Protobuf. In service_config.proto, load-balancing policy configuration uses a oneof. That works okay if you only ever use the policies built directly into the spec, but grpc-go lets anyone register a custom load balancer. So, of course, it’s not reasonable for gRPC to represent all the different load balancer configurations in a single oneof because the upstream .proto file in the gRPC repository would need to import a message definition for every custom balancer written by third-party teams. That’s not really feasible, so loosely defined JSON is used to sidestep that.

Hopefully this gives a bit more context on why service config works the way it does. Still, this is one more place where gRPC complicates the simple case to facilitate the most complex one.

Why isn’t there a typed Go API?

Even with pluggable backends, there could at least be a typed API for defining the built-in load-balancing policies. This has been requested a few times now. Back in 2019, grpc-go deprecated WithBalancerName and told users to switch to WithDefaultServiceConfig. By September of that year, issue #3003 was opened to ask for “another way to specify the configurations instead of using JSON.” A maintainer explained that JSON was “the service config format agreed upon by all the grpc languages,” though they agreed “it is reasonable to support specifying service using a format other than json, maybe a native go struct.” Other users in the thread were more direct: “Passing string configs like this is pretty weird.”

Occasionally, people kept bumping the thread to keep it alive. Finally, in March 2021, a maintainer stepped in to say that “this is unfortunately not something the team has resources to spend on right now.” Their position was that the JSON string “should be completely functional to use,” and because a proto definition existed, “there already technically is a native Go struct for service config.” (Though as we saw earlier, no gRPC project publishes that struct, and the JSON that protojson produces from it fails on some fields.)

As of November 2026, that issue is still open.

Even grpc-go’s other service configuration systems, like xDS, aren’t immune to this wart. The xDS control plane sends typed Protobuf messages, the xDS resolver in grpc-go translates them into a service config JSON string, and then the client channel immediately parses that JSON string back into Go structs. This is pretty silly.

The C# gRPC implementation shows how to do this better. Grpc.Net.Client has a ServiceConfig class with types like RoundRobinConfig and PickFirstConfig, and you can still register custom policies if you need them.

This post jabs a little hard at this API wart. In reality, it is manageable. You can always just use the JSON string literal and take the extra minute to ensure that it is valid and correct. go-grpc-middleware is also an alternative if you just need to configure retries.

Or just use ConnectRPC

gRPC libraries work like this because they bring a specific philosophy and technical perspective when building on top of other languages and on top of HTTP. The Go client has its own HTTP/2 transport, built using golang.org/x/net/http2 framing, and it handles name resolution, backend selection, and retries around that transport. You can’t pass it an http.Client. Since every gRPC implementation needs these same settings, JSON was a convenient way to share one config format across all of them.

ConnectRPC has a different philosophy, choosing the most standard way of building HTTP-based APIs and building on that. The Connect implementation for Go just uses Go’s standard net/http library. The generated client still speaks gRPC, gRPC-Web, or Connect, and its requests go through the HTTP client you supply. To change a timeout or a connection pool limit, you set it on that client or its transport.

This does leave a couple of aspects without a direct substitute in net/http. Client-side load balancing doesn’t really exist out of the box. Say DNS returns five pod IPs. An HTTP/2 client can connect to one pod and send every RPC there, and adding a sixth pod won’t help while the client keeps using that same connection. httplb checks DNS periodically and keeps connections open to the backends so it can spread requests across them. Like the grpc-go example, this assumes a headless Kubernetes Service, where DNS returns the pod IPs instead of a single cluster IP. Here’s the load-balancing half of the client from the top of this post, this time with httplb and connect-go v2:

httpClient := httplb.NewClient(
    httplb.WithPicker(picker.NewPowerOfTwo),
    httplb.WithDefaultTimeout(5*time.Second),
)
defer httpClient.Close()
 
client := myservicev1connect.NewMyServiceClient(connect.NewClient(
    connecthttp.NewTransport(
        httpClient,
        "https://my-service.default.svc.cluster.local:50051",
        connecthttp.WithGRPC(),
    ),
))

Round-robin is the default, so WithPicker is only needed to switch to something else, like power-of-two or fewest-pending. Options like WithResolver and WithHealthChecks work the same way. These are ordinary Go functions, so if you mistype WithPicker, the compiler tells you.

Another popular option for microservices is to skip the service config altogether by using a service mesh like Istio, Linkerd, or Cilium. If you’re already running a mesh, you can configure balancing and retries there, while also getting features like cross-service visibility and mTLS. Its proxy picks a backend for each RPC and applies the retry policy you give it. That works with either gRPC or Connect, so those policies can live outside the application.

The request for a typed Go API has been open since 2019. Seven years later, turning on round-robin in grpc-go still means handing it a JSON string.