SebastienMelki · SebastienMelki · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -71,7 +71,7 @@ func main() {
 | Plugin | Primary Function | Output | Dependencies |
 |--------|-----------------|---------|--------------|
 | `protoc-gen-go-http` | Generate HTTP handlers, routing & validation | `*_http*.pb.go` | `protoc-gen-go`, sebuf annotations |
-| `protoc-gen-go-client` | Generate type-safe Go HTTP clients | `*_client.pb.go` | `protoc-gen-go`, sebuf annotations |
+| `protoc-gen-go-client` | Generate type-safe Go HTTP clients | `*_client.pb.go` | `protoc-gen-go`, sebuf annotations; uses `go-http`-owned JSON mapping methods when generated alongside server code |
 | `protoc-gen-ts-client` | Generate type-safe TypeScript HTTP clients | `*_client.ts` | sebuf annotations |
 | `protoc-gen-ts-server` | Generate framework-agnostic TypeScript HTTP servers | `*_server.ts` | sebuf annotations |
 | `protoc-gen-openapiv3` | Generate OpenAPI specifications | `*.yaml`, `*.json` | None (standalone) |

diff --git a/docs/client-generation.md b/docs/client-generation.md
@@ -181,7 +181,15 @@ const (
 client := api.NewUserServiceClient("http://localhost:8080")
 ```
 
-The client automatically handles special JSON serialization, including messages with `unwrap` annotations for map values. See [JSON/Protobuf Compatibility](./json-protobuf-compatibility.md) for details.
+For JSON requests and responses, the client automatically uses custom sebuf JSON marshalers when they are present on your protobuf types. See [JSON/Protobuf Compatibility](./json-protobuf-compatibility.md) for details.
+
+> **JSON-mapping annotations require `go-http` generation.**
+> Package-level marshalers for annotations such as `unwrap`, `int64_encoding`,
+> `enum_encoding`, `nullable`, `empty_behavior`, `timestamp_format`,
+> `bytes_encoding`, `oneof_config`, and `flatten` are generated by
+> `protoc-gen-go-http`. If you generate only `go-client`, those annotations are
+> not applied to JSON client requests or responses. Generate `go-http` alongside
+> `go-client` in the same Go package when client JSON must honor them.
 
 ### Binary Protobuf
 

diff --git a/docs/json-protobuf-compatibility.md b/docs/json-protobuf-compatibility.md
@@ -116,7 +116,7 @@ With `unwrap`, the JSON output matches the desired format:
 When you use the `unwrap` annotation:
 
 1. **HTTP Generation**: sebuf generates custom `MarshalJSON()` and `UnmarshalJSON()` methods for messages containing maps with unwrapped values
-2. **Client Generation**: The generated client automatically uses the custom marshalers
+2. **Client Generation**: The generated client automatically uses those custom marshalers when they are present. Generate `protoc-gen-go-http` alongside `protoc-gen-go-client` when Go clients need sebuf JSON-mapping behavior.
 3. **OpenAPI Generation**: The OpenAPI schema shows the unwrapped structure (array values, not wrapper objects)
 
 ### Complete Example

diff --git a/examples/enum-params/buf.lock b/examples/enum-params/buf.lock
@@ -1,9 +1,6 @@
 # Generated by buf. DO NOT EDIT.
 version: v2
 deps:
-  - name: buf.build/bufbuild/protovalidate
-    commit: 50325440f8f24053b047484a6bf60b76
-    digest: b5:74cb6f5c0853c3c10aafc701614194bbd63326bdb8ef4068214454b8894b03ba4113e04b3a33a8321cdf05336e37db4dc14a5e2495db8462566914f36086ba31
   - name: buf.build/sebmelki/sebuf
     commit: b5f679ca6c5f4f148c3414adfea268d3
     digest: b5:007be9b0418e0284f34578307ba516b56259a29932bfd3b662515d3107d3886e2d47592edc580e4a520155c3ebed7b55375b90ac0fa327ccb603f17bf84d7eb1
diff --git a/examples/enum-params/go.mod b/examples/enum-params/go.mod
@@ -9,7 +9,7 @@ require (
 )
 
 require (
-	buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260415201107-50325440f8f2.1 // indirect
+	buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260709200747-435963d16310.1 // indirect
 	cel.dev/expr v0.25.1 // indirect
 	github.com/antlr4-go/antlr/v4 v4.13.1 // indirect
 	github.com/google/cel-go v0.28.0 // indirect

diff --git a/examples/enum-params/go.sum b/examples/enum-params/go.sum
@@ -1,5 +1,5 @@
-buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260415201107-50325440f8f2.1 h1:s6hzCXtND/ICdGPTMGk7C+/BFlr2Jg5GyH0NKf4XGXg=
-buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260415201107-50325440f8f2.1/go.mod h1:tvtbpgaVXZX4g6Pn+AnzFycuRK3MOz5HJfEGeEllXYM=
+buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260709200747-435963d16310.1 h1:fXh8CsdNpjRr8R5vFdqtIxPt/Lno2IIJlYOdZBIZn0w=
+buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260709200747-435963d16310.1/go.mod h1:tvtbpgaVXZX4g6Pn+AnzFycuRK3MOz5HJfEGeEllXYM=
 buf.build/go/protovalidate v1.2.0 h1:DQVrUWkmGTBij+kOYv/x2LLxwcLaGKMdzShj1/6/3H0=
 buf.build/go/protovalidate v1.2.0/go.mod h1:7rYiQEhqvAipoazpVNBBH2S2f8bjG4huMVy1V2Yofn4=
 cel.dev/expr v0.25.1 h1:1KrZg61W6TWSxuNZ37Xy49ps13NUovb66QLprthtwi4=

diff --git a/examples/error-handler/buf.lock b/examples/error-handler/buf.lock
@@ -2,8 +2,8 @@
 version: v2
 deps:
   - name: buf.build/bufbuild/protovalidate
-    commit: 2a1774d888024a9b93ce7eb4b59f6a83
-    digest: b5:6b7f9bc919b65e5b79d7b726ffc03d6f815a412d6b792970fa6f065cae162107bd0a9d47272c8ab1a2c9514e87b13d3fbf71df614374d62d2183afb64be2d30a
+    commit: 435963d1631043e694e56e6bcc3c79c3
+    digest: b5:f4ea07ad2dd94bd7243562f9908b9fb104feef8076040c89d9f7c1dedc074de4d4ce2b997686ef4400f3eccb765a7cfc20ed4acdd70b9a3699351245c61dba97
   - name: buf.build/sebmelki/sebuf
-    commit: 8af7d745b4554521bb89cde70a20ce0b
-    digest: b5:e676b75b804ae2b798c260e94309f3aa1e44d4b867dd7c8f5d8d634399765c44b6fda92de0574861d8d4bacc90a01c47fd04985a345b94441eedc87b500fbaf8
+    commit: b5f679ca6c5f4f148c3414adfea268d3
+    digest: b5:007be9b0418e0284f34578307ba516b56259a29932bfd3b662515d3107d3886e2d47592edc580e4a520155c3ebed7b55375b90ac0fa327ccb603f17bf84d7eb1
diff --git a/examples/error-handler/go.mod b/examples/error-handler/go.mod
@@ -3,7 +3,7 @@ module github.com/SebastienMelki/sebuf/examples/error-handler
 go 1.26.0
 
 require (
-	buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260209202127-80ab13bee0bf.1
+	buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260709200747-435963d16310.1
 	buf.build/go/protovalidate v0.14.0
 	github.com/SebastienMelki/sebuf v0.0.0-20250818125809-ff61bcf670dd
 	github.com/google/uuid v1.6.0

diff --git a/examples/error-handler/go.sum b/examples/error-handler/go.sum
@@ -1,6 +1,5 @@
-buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20251209175733-2a1774d88802.1 h1:j9yeqTWEFrtimt8Nng2MIeRrpoCvQzM9/g25XTvqUGg=
-buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20251209175733-2a1774d88802.1/go.mod h1:tvtbpgaVXZX4g6Pn+AnzFycuRK3MOz5HJfEGeEllXYM=
-buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260209202127-80ab13bee0bf.1/go.mod h1:tvtbpgaVXZX4g6Pn+AnzFycuRK3MOz5HJfEGeEllXYM=
+buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260709200747-435963d16310.1 h1:fXh8CsdNpjRr8R5vFdqtIxPt/Lno2IIJlYOdZBIZn0w=
+buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260709200747-435963d16310.1/go.mod h1:tvtbpgaVXZX4g6Pn+AnzFycuRK3MOz5HJfEGeEllXYM=
 buf.build/go/protovalidate v0.14.0 h1:kr/rC/no+DtRyYX+8KXLDxNnI1rINz0imk5K44ZpZ3A=
 buf.build/go/protovalidate v0.14.0/go.mod h1:+F/oISho9MO7gJQNYC2VWLzcO1fTPmaTA08SDYJZncA=
 cel.dev/expr v0.23.1 h1:K4KOtPCJQjVggkARsjG9RWXP6O4R73aHeJMa/dmCQQg=

diff --git a/examples/market-data-unwrap/README.md b/examples/market-data-unwrap/README.md
@@ -208,7 +208,7 @@ go run main.go
 go run client_example.go
 ```
 
-The generated client handles all the unwrap serialization automatically:
+Because this example generates `protoc-gen-go-http` alongside `protoc-gen-go-client`, the generated client uses the go-http-owned unwrap marshalers automatically:
 
 ```go
 package main
@@ -282,8 +282,8 @@ docker run -p 8081:8080 -v $(pwd)/docs:/app swaggerapi/swagger-ui
 ### How Unwrap Works
 
 1. **Proto definition**: Mark one repeated field in a message with `[(sebuf.http.unwrap) = true]`
-2. **Code generation**: sebuf generates custom `MarshalJSON()` and `UnmarshalJSON()` methods
-3. **Runtime**: When the message is a map value, JSON serialization collapses the wrapper
+2. **Code generation**: `protoc-gen-go-http` generates custom `MarshalJSON()` and `UnmarshalJSON()` methods
+3. **Runtime**: When the message is a map value, JSON serialization collapses the wrapper; the generated Go client uses those methods when go-http is generated into the same package
 
 ### Constraints
 
@@ -295,8 +295,8 @@ docker run -p 8081:8080 -v $(pwd)/docs:/app swaggerapi/swagger-ui
 
 | File | Description |
 |------|-------------|
-| `*_unwrap.pb.go` | Custom JSON marshaling for messages with unwrap fields |
-| `*_client.pb.go` | HTTP client that uses the custom marshalers |
+| `*_unwrap.pb.go` | go-http-owned custom JSON marshaling for messages with unwrap fields |
+| `*_client.pb.go` | HTTP client that uses the custom marshalers when present |
 | `*.openapi.yaml` | OpenAPI spec with correct array schemas |
 
 ## Troubleshooting
@@ -306,7 +306,7 @@ docker run -p 8081:8080 -v $(pwd)/docs:/app swaggerapi/swagger-ui
 - Run `make clean && make generate` to regenerate code
 
 **Client not handling unwrap correctly?**
-- The client uses custom marshalers automatically
+- Generate `protoc-gen-go-http` alongside `protoc-gen-go-client`; go-http owns the custom marshalers
 - Check that you're using the generated client, not manual HTTP calls
 
 **OpenAPI shows object instead of array for map values?**

diff --git a/examples/market-data-unwrap/api/proto/services/market_data_service_client.pb.go b/examples/market-data-unwrap/api/proto/services/market_data_service_client.pb.go
diff --git a/examples/market-data-unwrap/api/proto/services/market_data_service_http.pb.go b/examples/market-data-unwrap/api/proto/services/market_data_service_http.pb.go