google.golang.org/protobuf v1.36.12: Control JSON formatting and parsing of Protocol Buffers messages using protojson MarshalOptions and UnmarshalOptions

# Protocol Buffers JSON Serialization and Parsing Behavior

A known-solution search for `google.golang.org/protobuf` identified an existing sample (sha256:483581752059a6c7b423f8e927bd877e782e82da6eb0bffd094f66af376e53b7) addressing registration conflict configuration via `GOLANG_PROTOBUF_REGISTRATION_CONFLICT`. A specific query for `protojson` serialization and deserialization options yielded no safe match.

This sample tests and verifies the behavior of `google.golang.org/protobuf/encoding/protojson` pinned to release `v1.36.12`.

## Observed Behavior

1. **Default Field Emission**:
   By default, `protojson.Marshal` omits unpopulated fields. For proto3 messages, fields holding default zero values (e.g., `0`, `""`, `false`), empty repeated lists, and nil submessage references are excluded from the output JSON.

2. **Populating Defaults (`EmitUnpopulated`)**:
   When `protojson.MarshalOptions{EmitUnpopulated: true}` is specified, zero-valued scalar fields are serialized (e.g., `""`, `0`, `false`), repeated fields are rendered as empty arrays (`[]`), and unset submessage pointers are output as `null`.

3. **Field Naming (`UseProtoNames`)**:
   Standard JSON mapping uses camelCase names derived from field definitions or explicit `json_name` tags. Enabling `UseProtoNames: true` preserves original snake_case field identifiers in the JSON output.

4. **Enum Value Representation (`UseEnumNumbers`)**:
   By default, enum values serialize as their string identifier (e.g., `"ROLE_ADMIN"`). Setting `UseEnumNumbers: true` serializes enum fields as numeric integers (e.g., `1`).

5. **Well-Known Type Representation**:
   Special well-known types defined in `google.golang.org/protobuf/types/known` are mapped directly to canonical JSON structures:
   - `google.protobuf.Timestamp` formats as an RFC 3339 timestamp string (e.g., `"2026-08-17T12:00:00Z"`).
   - `google.protobuf.Struct` formats as a native JSON object rather than nested protobuf field representations.

6. **Unknown Field Parsing (`DiscardUnknown`)**:
   By default, `protojson.Unmarshal` rejects unknown JSON keys with an error containing `unknown field`. Setting `protojson.UnmarshalOptions{DiscardUnknown: true}` allows unknown fields to be safely ignored during parsing.

{"case":{"caseId":"case:sha256:ecfd5acd294a822581d67015a75b1e6e6c170ac73f2f3cb96d73df8d28772c32","contract":["By default protojson.Marshal omits unpopulated or zero-valued fields, but protojson.MarshalOptions with EmitUnpopulated set to true includes default values for scalar fields, empty arrays for repeated fields, and null for unset message fields.","Setting protojson.MarshalOptions.UseProtoNames to true formats JSON keys using original snake_case protobuf field names instead of camelCase json_name.","Setting protojson.MarshalOptions.UseEnumNumbers to true serializes enum values as their numeric integers rather than enum string identifiers.","Well-known types such as google.protobuf.Timestamp and google.protobuf.Struct serialize directly to RFC 3339 formatted strings and native JSON objects respectively.","By default protojson.Unmarshal rejects JSON payloads containing unknown keys with an error, whereas protojson.UnmarshalOptions with DiscardUnknown set to true silently discards unrecognized fields."],"goal":"Control JSON formatting and parsing of Protocol Buffers messages using protojson MarshalOptions and UnmarshalOptions","kind":"HOW","packages":["pkg:golang/google.golang.org/protobuf@v1.36.12"],"schemaVersion":1,"symbols":["google.golang.org/protobuf/encoding/protojson.Marshal","google.golang.org/protobuf/encoding/protojson.MarshalOptions","google.golang.org/protobuf/encoding/protojson.Unmarshal","google.golang.org/protobuf/encoding/protojson.UnmarshalOptions"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","ecosystem":"golang","executionContext":"go","language":"go","os":"linux","packageManager":"go","runtime":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/google.golang.org/protobuf@v1.36.12"],"schemaVersion":1,"symbols":["google.golang.org/protobuf/encoding/protojson.Marshal","google.golang.org/protobuf/encoding/protojson.MarshalOptions","google.golang.org/protobuf/encoding/protojson.Unmarshal","google.golang.org/protobuf/encoding/protojson.UnmarshalOptions"],"verifierAdapter":"golang@1"}

module example.com/protojson-behavior

go 1.25.0

require google.golang.org/protobuf v1.36.12

github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=

package protojsontest

import (
	"encoding/json"
	"strings"
	"testing"
	"time"

	"google.golang.org/protobuf/encoding/protojson"
	"google.golang.org/protobuf/proto"
	"google.golang.org/protobuf/reflect/protodesc"
	"google.golang.org/protobuf/reflect/protoreflect"
	"google.golang.org/protobuf/reflect/protoregistry"
	"google.golang.org/protobuf/types/descriptorpb"
	"google.golang.org/protobuf/types/dynamicpb"
	"google.golang.org/protobuf/types/known/structpb"
	"google.golang.org/protobuf/types/known/timestamppb"
)

// buildSchema creates dynamic message descriptors for testing protojson formatting and parsing.
func buildSchema(t *testing.T) (protoreflect.MessageDescriptor, protoreflect.MessageDescriptor) {
	t.Helper()

	fd := &descriptorpb.FileDescriptorProto{
		Name:    proto.String("user_account.proto"),
		Package: proto.String("example.user"),
		Syntax:  proto.String("proto3"),
		Dependency: []string{
			"google/protobuf/timestamp.proto",
			"google/protobuf/struct.proto",
		},
		EnumType: []*descriptorpb.EnumDescriptorProto{
			{
				Name: proto.String("UserRole"),
				Value: []*descriptorpb.EnumValueDescriptorProto{
					{Name: proto.String("ROLE_UNSPECIFIED"), Number: proto.Int32(0)},
					{Name: proto.String("ROLE_ADMIN"), Number: proto.Int32(1)},
					{Name: proto.String("ROLE_MEMBER"), Number: proto.Int32(2)},
				},
			},
		},
		MessageType: []*descriptorpb.DescriptorProto{
			{
				Name: proto.String("Config"),
				Field: []*descriptorpb.FieldDescriptorProto{
					{
						Name:     proto.String("timeout_ms"),
						Number:   proto.Int32(1),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_INT32.Enum(),
						JsonName: proto.String("timeoutMs"),
					},
					{
						Name:     proto.String("retry_count"),
						Number:   proto.Int32(2),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_INT32.Enum(),
						JsonName: proto.String("retryCount"),
					},
				},
			},
			{
				Name: proto.String("UserAccount"),
				Field: []*descriptorpb.FieldDescriptorProto{
					{
						Name:     proto.String("id"),
						Number:   proto.Int32(1),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_INT64.Enum(),
						JsonName: proto.String("id"),
					},
					{
						Name:     proto.String("user_name"),
						Number:   proto.Int32(2),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
						JsonName: proto.String("userName"),
					},
					{
						Name:     proto.String("is_active"),
						Number:   proto.Int32(3),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_BOOL.Enum(),
						JsonName: proto.String("isActive"),
					},
					{
						Name:     proto.String("role"),
						Number:   proto.Int32(4),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_ENUM.Enum(),
						TypeName: proto.String(".example.user.UserRole"),
						JsonName: proto.String("role"),
					},
					{
						Name:     proto.String("tags"),
						Number:   proto.Int32(5),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_STRING.Enum(),
						Label:    descriptorpb.FieldDescriptorProto_LABEL_REPEATED.Enum(),
						JsonName: proto.String("tags"),
					},
					{
						Name:     proto.String("created_at"),
						Number:   proto.Int32(6),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(),
						TypeName: proto.String(".google.protobuf.Timestamp"),
						JsonName: proto.String("createdAt"),
					},
					{
						Name:     proto.String("extra_data"),
						Number:   proto.Int32(7),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(),
						TypeName: proto.String(".google.protobuf.Struct"),
						JsonName: proto.String("extraData"),
					},
					{
						Name:     proto.String("nested_config"),
						Number:   proto.Int32(8),
						Type:     descriptorpb.FieldDescriptorProto_TYPE_MESSAGE.Enum(),
						TypeName: proto.String(".example.user.Config"),
						JsonName: proto.String("nestedConfig"),
					},
				},
			},
		},
	}

	fileDesc, err := protodesc.NewFile(fd, protoregistry.GlobalFiles)
	if err != nil {
		t.Fatalf("protodesc.NewFile failed: %v", err)
	}

	userMsgDesc := fileDesc.Messages().ByName("UserAccount")
	configDesc := fileDesc.Messages().ByName("Config")
	if userMsgDesc == nil || configDesc == nil {
		t.Fatalf("failed to find message descriptors in file descriptor")
	}

	return userMsgDesc, configDesc
}

func TestProtojsonDefaultMarshalOmitsZeroValues(t *testing.T) {
	userMsgDesc, _ := buildSchema(t)
	msg := dynamicpb.NewMessage(userMsgDesc)

	// Set only ID, leave other fields at proto3 default values (empty string, false, 0 enum, empty list, nil submessages)
	idField := userMsgDesc.Fields().ByName("id")
	msg.Set(idField, protoreflect.ValueOfInt64(42))

	data, err := protojson.Marshal(msg)
	if err != nil {
		t.Fatalf("protojson.Marshal failed: %v", err)
	}

	var parsed map[string]any
	if err := json.Unmarshal(data, &parsed); err != nil {
		t.Fatalf("json.Unmarshal failed: %v", err)
	}

	// Default marshaling emits only populated fields (and non-default values for scalars)
	if _, ok := parsed["id"]; !ok {
		t.Errorf("expected 'id' to be present in default JSON, got: %s", string(data))
	}
	if _, ok := parsed["userName"]; ok {
		t.Errorf("expected 'userName' to be omitted by default, got: %s", string(data))
	}
	if _, ok := parsed["isActive"]; ok {
		t.Errorf("expected 'isActive' to be omitted by default, got: %s", string(data))
	}
	if _, ok := parsed["role"]; ok {
		t.Errorf("expected 'role' (default enum 0) to be omitted by default, got: %s", string(data))
	}
	if _, ok := parsed["tags"]; ok {
		t.Errorf("expected 'tags' (empty list) to be omitted by default, got: %s", string(data))
	}
	if _, ok := parsed["nestedConfig"]; ok {
		t.Errorf("expected 'nestedConfig' (nil message) to be omitted by default, got: %s", string(data))
	}
}

func TestProtojsonEmitUnpopulatedIncludesDefaults(t *testing.T) {
	userMsgDesc, _ := buildSchema(t)
	msg := dynamicpb.NewMessage(userMsgDesc)

	idField := userMsgDesc.Fields().ByName("id")
	msg.Set(idField, protoreflect.ValueOfInt64(100))

	opts := protojson.MarshalOptions{
		EmitUnpopulated: true,
	}
	data, err := opts.Marshal(msg)
	if err != nil {
		t.Fatalf("opts.Marshal failed: %v", err)
	}

	var parsed map[string]any
	if err := json.Unmarshal(data, &parsed); err != nil {
		t.Fatalf("json.Unmarshal failed: %v", err)
	}

	// With EmitUnpopulated: true, unpopulated scalar fields, enums, lists, and nil messages are emitted with default values
	if parsed["userName"] != "" {
		t.Errorf("expected userName to be empty string, got: %v", parsed["userName"])
	}
	if parsed["isActive"] != false {
		t.Errorf("expected isActive to be false, got: %v", parsed["isActive"])
	}
	if parsed["role"] != "ROLE_UNSPECIFIED" {
		t.Errorf("expected role to be ROLE_UNSPECIFIED, got: %v", parsed["role"])
	}
	tags, ok := parsed["tags"].([]any)
	if !ok || len(tags) != 0 {
		t.Errorf("expected tags to be empty array [], got: %v", parsed["tags"])
	}
	if parsed["nestedConfig"] != nil {
		t.Errorf("expected nestedConfig to be null, got: %v", parsed["nestedConfig"])
	}
}

func TestProtojsonUseProtoNames(t *testing.T) {
	userMsgDesc, _ := buildSchema(t)
	msg := dynamicpb.NewMessage(userMsgDesc)

	userField := userMsgDesc.Fields().ByName("user_name")
	msg.Set(userField, protoreflect.ValueOfString("alice"))

	// Default uses camelCase json_name ("userName")
	defaultData, err := protojson.Marshal(msg)
	if err != nil {
		t.Fatalf("protojson.Marshal failed: %v", err)
	}
	if !strings.Contains(string(defaultData), `"userName":"alice"`) {
		t.Errorf("expected default protojson to use 'userName', got: %s", string(defaultData))
	}

	// UseProtoNames: true uses original snake_case field name ("user_name")
	opts := protojson.MarshalOptions{
		UseProtoNames: true,
	}
	protoNameData, err := opts.Marshal(msg)
	if err != nil {
		t.Fatalf("opts.Marshal failed: %v", err)
	}
	if !strings.Contains(string(protoNameData), `"user_name":"alice"`) {
		t.Errorf("expected UseProtoNames to emit 'user_name', got: %s", string(protoNameData))
	}
}

func TestProtojsonUseEnumNumbers(t *testing.T) {
	userMsgDesc, _ := buildSchema(t)
	msg := dynamicpb.NewMessage(userMsgDesc)

	roleField := userMsgDesc.Fields().ByName("role")
	msg.Set(roleField, protoreflect.ValueOfEnum(1)) // ROLE_ADMIN = 1

	// Default emits string name
	defaultData, err := protojson.Marshal(msg)
	if err != nil {
		t.Fatalf("protojson.Marshal failed: %v", err)
	}
	if !strings.Contains(string(defaultData), `"role":"ROLE_ADMIN"`) {
		t.Errorf("expected default protojson to emit string enum 'ROLE_ADMIN', got: %s", string(defaultData))
	}

	// UseEnumNumbers: true emits integer value
	opts := protojson.MarshalOptions{
		UseEnumNumbers: true,
	}
	enumNumData, err := opts.Marshal(msg)
	if err != nil {
		t.Fatalf("opts.Marshal failed: %v", err)
	}
	if !strings.Contains(string(enumNumData), `"role":1`) {
		t.Errorf("expected UseEnumNumbers to emit integer 1, got: %s", string(enumNumData))
	}
}

func TestProtojsonWellKnownTypesFormatting(t *testing.T) {
	userMsgDesc, _ := buildSchema(t)
	msg := dynamicpb.NewMessage(userMsgDesc)

	// Timestamp field
	fixedTime := time.Date(2026, 8, 17, 12, 0, 0, 0, time.UTC)
	ts := timestamppb.New(fixedTime)
	tsField := userMsgDesc.Fields().ByName("created_at")
	msg.Set(tsField, protoreflect.ValueOfMessage(ts.ProtoReflect()))

	// Struct field
	structVal, err := structpb.NewStruct(map[string]any{
		"env":     "production",
		"version": 42,
		"enabled": true,
	})
	if err != nil {
		t.Fatalf("structpb.NewStruct failed: %v", err)
	}
	structField := userMsgDesc.Fields().ByName("extra_data")
	msg.Set(structField, protoreflect.ValueOfMessage(structVal.ProtoReflect()))

	data, err := protojson.Marshal(msg)
	if err != nil {
		t.Fatalf("protojson.Marshal failed: %v", err)
	}

	var parsed struct {
		CreatedAt string         `json:"createdAt"`
		ExtraData map[string]any `json:"extraData"`
	}
	if err := json.Unmarshal(data, &parsed); err != nil {
		t.Fatalf("json.Unmarshal failed: %v", err)
	}

	// google.protobuf.Timestamp formats as RFC 3339 string
	if parsed.CreatedAt != "2026-08-17T12:00:00Z" {
		t.Errorf("expected createdAt to be formatted as RFC3339 timestamp, got: %q", parsed.CreatedAt)
	}

	// google.protobuf.Struct formats as raw JSON object
	if parsed.ExtraData["env"] != "production" || parsed.ExtraData["enabled"] != true {
		t.Errorf("expected extraData to match structpb contents, got: %+v", parsed.ExtraData)
	}
}

func TestProtojsonUnmarshalDiscardUnknownBehavior(t *testing.T) {
	userMsgDesc, _ := buildSchema(t)

	jsonPayload := `{"id":123,"userName":"bob","unknownField":"ignored_or_error"}`

	// Default unmarshaling rejects unknown fields
	targetMsg1 := dynamicpb.NewMessage(userMsgDesc)
	errDefault := protojson.Unmarshal([]byte(jsonPayload), targetMsg1)
	if errDefault == nil {
		t.Fatalf("expected protojson.Unmarshal to return error on unknown field, got nil")
	}
	if !strings.Contains(errDefault.Error(), "unknown field") {
		t.Fatalf("expected error message to mention 'unknown field', got: %v", errDefault)
	}

	// With DiscardUnknown: true, unknown fields are silently skipped
	opts := protojson.UnmarshalOptions{
		DiscardUnknown: true,
	}
	targetMsg2 := dynamicpb.NewMessage(userMsgDesc)
	if err := opts.Unmarshal([]byte(jsonPayload), targetMsg2); err != nil {
		t.Fatalf("expected DiscardUnknown to succeed without error, got: %v", err)
	}

	idField := userMsgDesc.Fields().ByName("id")
	userField := userMsgDesc.Fields().ByName("user_name")
	if targetMsg2.Get(idField).Int() != 123 {
		t.Errorf("expected id to be 123, got: %d", targetMsg2.Get(idField).Int())
	}
	if targetMsg2.Get(userField).String() != "bob" {
		t.Errorf("expected userName to be 'bob', got: %q", targetMsg2.Get(userField).String())
	}
}