From 0895e50495fefad1a0645267084f0d64a1439a98 Mon Sep 17 00:00:00 2001 From: intech Date: Thu, 4 Jun 2026 22:54:35 +0400 Subject: [PATCH] docs(core): document server-level jsonOptions and per-service form Document the new `jsonOptions` option on `createServer()` for controlling Connect JSON serialization server-wide (e.g. `alwaysEmitImplicit: true`), plus the per-service `router.service()` form. Note the protobuf-es v2 field name (`alwaysEmitImplicit`, not the v1 `emitDefaultValues`). Co-Authored-By: Claude Opus 4.8 (1M context) --- en/packages/core.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/en/packages/core.md b/en/packages/core.md index 9985971..8151e33 100644 --- a/en/packages/core.md +++ b/en/packages/core.md @@ -81,6 +81,39 @@ The server is created in `CREATED` state. Call `server.start()` to begin accepti | `handshakeTimeout` | `number` | `30000` | Handshake timeout in milliseconds | | `eventBus` | `EventBusLike` | `undefined` | Event bus for lifecycle management | | `http2Options` | `SecureServerOptions` | `undefined` | Additional HTTP/2 server options | +| `jsonOptions` | `Partial` | `undefined` | Connect JSON serialization options applied server-wide. See [JSON serialization](#json-serialization). | + +### JSON serialization + +By default, Connect omits fields with implicit presence from JSON responses +(proto3 scalar `0`, empty string, empty list, enum default). Set `jsonOptions` +to change this server-wide -- it is passed to the underlying `connectNodeAdapter`, +so it also applies to framework-registered protocol services (healthcheck, +reflection). + +```typescript +const server = createServer({ + services: [routes], + // Include zero/default fields in JSON responses instead of omitting them. + jsonOptions: { alwaysEmitImplicit: true }, +}); +``` + +::: tip protobuf-es v2 field name +The relevant `JsonWriteOptions` field is `alwaysEmitImplicit` (it was named +`emitDefaultValues` in protobuf-es v1, which does not apply to Connectum). +::: + +For per-service control, pass the same option as the third argument of +`router.service()` inside a service route, instead of setting it server-wide: + +```typescript +const routes: ServiceRoute = (router) => { + router.service(MyService, myImpl, { + jsonOptions: { alwaysEmitImplicit: true }, + }); +}; +``` ### `Server` Interface