google.golang.org/protobuf v1.36.10: protojson.MarshalOptions

# Protocol Buffers protojson.MarshalOptions Serialization Semantics

A search for `protojson.MarshalOptions` in `pkg:golang/google.golang.org/protobuf@v1.36.10` returned `NO_SAFE_MATCH`.

This sample verifies the serialization options and behavior provided by `protojson.MarshalOptions`.

## Observed Behavior

1. **Multiline and Indentation (`Multiline`, `Indent`, `Format`)**:
   - Setting `Multiline: false` produces compact single-line JSON.
   - Setting `Multiline: true` formats JSON with newlines and colon spacing.
   - Setting `Indent: "    "` sets 4-space indentation per nesting level.
   - `MarshalOptions.Format(m)` returns string representation identical to `Marshal(m)`.

2. **Appending to Buffer (`MarshalAppend`)**:
   - `MarshalOptions.MarshalAppend(dst, m)` appends the serialized JSON payload to `dst` without mutating prefix data.

3. **Field Naming Convention (`UseProtoNames`)**:
   - When `UseProtoNames: false` (default), fields are serialized using lowerCamelCase (e.g. `fileName`).
   - When `UseProtoNames: true`, fields are serialized using original protobuf field names (e.g. `file_name`).

4. **Enum Serialization (`UseEnumNumbers`)**:
   - When `UseEnumNumbers: false` (default), enums are serialized as string identifiers (e.g. `"TYPE_STRING"`).
   - When `UseEnumNumbers: true`, enums are serialized as integer numbers (e.g. `9`).

5. **Default & Zero-Value Fields (`EmitUnpopulated`)**:
   - When `EmitUnpopulated: false` (default), zero-value proto3 fields are omitted (`{}`).
   - When `EmitUnpopulated: true`, default zero-value fields are emitted (e.g. `{"fileName":""}`).

6. **Any Message Resolution (`Resolver`)**:
   - `Resolver` resolves `anypb.Any` type URLs and marshals inner protobuf messages inline with `@type`.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify protojson.MarshalOptions in pkg:golang/google.golang.org/protobuf@v1.36.10
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/google.golang.org/protobuf@v1.36.10
Demonstrate these symbols/APIs:
  - protojson.MarshalOptions

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:ae76f2fc423efd1c24001f4a13b25626da737b5288735bdb97b4381392142889","contract":["protojson.MarshalOptions with Multiline and Indent formats serialized JSON with configured indent spacing and newlines, and Format produces output matching Marshal.","protojson.MarshalOptions.MarshalAppend appends marshaled JSON bytes directly to a destination byte slice.","protojson.MarshalOptions with UseProtoNames controls whether field names are serialized using original proto field names (snake_case) or lowerCamelCase JSON names.","protojson.MarshalOptions with UseEnumNumbers controls whether enum values are serialized as numeric integers or string identifiers.","protojson.MarshalOptions with EmitUnpopulated controls whether default zero-value proto3 fields are omitted or included in JSON output.","protojson.MarshalOptions with Resolver correctly resolves and serializes anypb.Any messages containing well-known or custom registered protobuf types.","protojson.MarshalOptions supports complex nested message serialization combining structpb.Struct and apipb.Api."],"goal":"verify protojson.MarshalOptions in pkg:golang/google.golang.org/protobuf@v1.36.10","kind":"HOW","packages":["pkg:golang/google.golang.org/protobuf@v1.36.10"],"schemaVersion":1,"symbols":["protojson.MarshalOptions"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","executionContext":"go","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","runtime":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/google.golang.org/protobuf@v1.36.10"],"schemaVersion":1,"subject":"pkg:golang/google.golang.org/protobuf@v1.36.10","symbols":["protojson.MarshalOptions"],"verifierAdapter":"golang@1"}

module example.com/protojsondemo

go 1.23

require google.golang.org/protobuf v1.36.10

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.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=

package protojsondemo_test

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

	"google.golang.org/protobuf/encoding/protojson"
	"google.golang.org/protobuf/reflect/protoregistry"
	"google.golang.org/protobuf/types/known/anypb"
	"google.golang.org/protobuf/types/known/apipb"
	"google.golang.org/protobuf/types/known/sourcecontextpb"
	"google.golang.org/protobuf/types/known/structpb"
	"google.golang.org/protobuf/types/known/typepb"
)

// TestMarshalOptionsMultilineAndIndent verifies Multiline and Indent formatting,
// along with Format and Marshal parity.
func TestMarshalOptionsMultilineAndIndent(t *testing.T) {
	msg := &sourcecontextpb.SourceContext{
		FileName: "service/schema.proto",
	}

	// 1. Single-line default (Multiline: false)
	optsSingle := protojson.MarshalOptions{
		Multiline: false,
	}
	outSingle, err := optsSingle.Marshal(msg)
	if err != nil {
		t.Fatalf("Marshal with Multiline: false failed: %v", err)
	}
	if strings.Contains(string(outSingle), "\n") {
		t.Fatalf("expected single-line JSON, got: %s", string(outSingle))
	}
	if string(outSingle) != `{"fileName":"service/schema.proto"}` {
		t.Fatalf("expected compact JSON, got: %s", string(outSingle))
	}

	// 2. Multiline with custom indentation
	optsMulti := protojson.MarshalOptions{
		Multiline: true,
		Indent:    "    ", // 4 spaces
	}
	outMulti, err := optsMulti.Marshal(msg)
	if err != nil {
		t.Fatalf("Marshal with Multiline: true failed: %v", err)
	}
	expectedMulti := "{\n    \"fileName\": \"service/schema.proto\"\n}"
	if string(outMulti) != expectedMulti {
		t.Fatalf("unexpected Multiline output:\nwant:\n%s\ngot:\n%s", expectedMulti, string(outMulti))
	}

	// 3. Format() produces string matching Marshal()
	formatted := optsMulti.Format(msg)
	if formatted != string(outMulti) {
		t.Fatalf("Format() mismatch: want %q, got %q", string(outMulti), formatted)
	}
}

// TestMarshalOptionsMarshalAppend verifies appending marshaled JSON to an existing buffer.
func TestMarshalOptionsMarshalAppend(t *testing.T) {
	msg := &sourcecontextpb.SourceContext{
		FileName: "config.proto",
	}

	opts := protojson.MarshalOptions{}
	prefix := []byte("HEADER:")
	result, err := opts.MarshalAppend(prefix, msg)
	if err != nil {
		t.Fatalf("MarshalAppend failed: %v", err)
	}

	if !bytes.HasPrefix(result, prefix) {
		t.Fatalf("expected prefix 'HEADER:', got: %s", string(result))
	}

	jsonPayload := result[len(prefix):]
	var parsed map[string]interface{}
	if err := json.Unmarshal(jsonPayload, &parsed); err != nil {
		t.Fatalf("failed to parse appended JSON payload %s: %v", string(jsonPayload), err)
	}
	if parsed["fileName"] != "config.proto" {
		t.Fatalf("expected fileName 'config.proto', got: %v", parsed["fileName"])
	}
}

// TestMarshalOptionsUseProtoNames verifies UseProtoNames controls snake_case vs camelCase field naming.
func TestMarshalOptionsUseProtoNames(t *testing.T) {
	msg := &sourcecontextpb.SourceContext{
		FileName: "models/user.proto",
	}

	// Default: lowerCamelCase (fileName)
	optsDefault := protojson.MarshalOptions{
		UseProtoNames: false,
	}
	outDefault, err := optsDefault.Marshal(msg)
	if err != nil {
		t.Fatalf("Marshal with UseProtoNames: false failed: %v", err)
	}
	if !strings.Contains(string(outDefault), `"fileName"`) {
		t.Fatalf("expected camelCase 'fileName' in %s", string(outDefault))
	}

	// UseProtoNames: true uses original proto name (file_name)
	optsProtoNames := protojson.MarshalOptions{
		UseProtoNames: true,
	}
	outProtoNames, err := optsProtoNames.Marshal(msg)
	if err != nil {
		t.Fatalf("Marshal with UseProtoNames: true failed: %v", err)
	}
	if !strings.Contains(string(outProtoNames), `"file_name"`) {
		t.Fatalf("expected snake_case 'file_name' in %s", string(outProtoNames))
	}
}

// TestMarshalOptionsUseEnumNumbers verifies UseEnumNumbers emits enum integers instead of string names.
func TestMarshalOptionsUseEnumNumbers(t *testing.T) {
	fieldMsg := &typepb.Field{
		Name: "user_id",
		Kind: typepb.Field_TYPE_STRING, // enum value 9
	}

	// Default: enum string name ("TYPE_STRING")
	optsString := protojson.MarshalOptions{
		UseEnumNumbers: false,
	}
	outString, err := optsString.Marshal(fieldMsg)
	if err != nil {
		t.Fatalf("Marshal with UseEnumNumbers: false failed: %v", err)
	}
	if !strings.Contains(string(outString), `"kind":"TYPE_STRING"`) {
		t.Fatalf("expected string enum '\"kind\":\"TYPE_STRING\"', got: %s", string(outString))
	}

	// UseEnumNumbers: true -> integer value 9
	optsNumbers := protojson.MarshalOptions{
		UseEnumNumbers: true,
	}
	outNumbers, err := optsNumbers.Marshal(fieldMsg)
	if err != nil {
		t.Fatalf("Marshal with UseEnumNumbers: true failed: %v", err)
	}
	if !strings.Contains(string(outNumbers), `"kind":9`) {
		t.Fatalf("expected numeric enum '\"kind\":9', got: %s", string(outNumbers))
	}
}

// TestMarshalOptionsEmitUnpopulated verifies EmitUnpopulated emits default/zero proto3 fields.
func TestMarshalOptionsEmitUnpopulated(t *testing.T) {
	msg := &sourcecontextpb.SourceContext{
		FileName: "", // zero/default value
	}

	// Default (EmitUnpopulated: false): zero values omitted -> "{}"
	optsOmit := protojson.MarshalOptions{
		EmitUnpopulated: false,
	}
	outOmit, err := optsOmit.Marshal(msg)
	if err != nil {
		t.Fatalf("Marshal with EmitUnpopulated: false failed: %v", err)
	}
	if string(outOmit) != "{}" {
		t.Fatalf("expected '{}', got: %s", string(outOmit))
	}

	// EmitUnpopulated: true -> includes zero values
	optsEmit := protojson.MarshalOptions{
		EmitUnpopulated: true,
	}
	outEmit, err := optsEmit.Marshal(msg)
	if err != nil {
		t.Fatalf("Marshal with EmitUnpopulated: true failed: %v", err)
	}
	if string(outEmit) != `{"fileName":""}` {
		t.Fatalf("expected '{\"fileName\":\"\"}', got: %s", string(outEmit))
	}
}

// TestMarshalOptionsResolverWithAny verifies custom Resolver resolves and marshals anypb.Any.
func TestMarshalOptionsResolverWithAny(t *testing.T) {
	inner := &sourcecontextpb.SourceContext{
		FileName: "nested/spec.proto",
	}
	anyMsg, err := anypb.New(inner)
	if err != nil {
		t.Fatalf("anypb.New failed: %v", err)
	}

	// Default resolver (protoregistry.GlobalTypes) resolves well-known types
	opts := protojson.MarshalOptions{
		Resolver: protoregistry.GlobalTypes,
	}
	out, err := opts.Marshal(anyMsg)
	if err != nil {
		t.Fatalf("Marshal with Resolver failed: %v", err)
	}

	var parsed map[string]interface{}
	if err := json.Unmarshal(out, &parsed); err != nil {
		t.Fatalf("failed to parse Any JSON %s: %v", string(out), err)
	}

	if parsed["@type"] != "type.googleapis.com/google.protobuf.SourceContext" {
		t.Fatalf("expected @type 'type.googleapis.com/google.protobuf.SourceContext', got: %v", parsed["@type"])
	}
	if parsed["fileName"] != "nested/spec.proto" {
		t.Fatalf("expected fileName 'nested/spec.proto', got: %v", parsed["fileName"])
	}
}

// TestMarshalOptionsStructAndApiComposition verifies marshaling complex nested messages
// with combinations of MarshalOptions.
func TestMarshalOptionsStructAndApiComposition(t *testing.T) {
	st, err := structpb.NewStruct(map[string]interface{}{
		"metric": "cpu_utilization",
		"value":  98.6,
	})
	if err != nil {
		t.Fatalf("structpb.NewStruct failed: %v", err)
	}

	api := &apipb.Api{
		Name:    "v1.ComputeService",
		Version: "v1.0",
		SourceContext: &sourcecontextpb.SourceContext{
			FileName: "compute.proto",
		},
	}

	opts := protojson.MarshalOptions{
		Multiline:     true,
		Indent:        "  ",
		UseProtoNames: true,
	}

	// Marshal structpb
	stOut, err := opts.Marshal(st)
	if err != nil {
		t.Fatalf("Marshal Struct failed: %v", err)
	}
	if !strings.Contains(string(stOut), `"cpu_utilization"`) {
		t.Fatalf("missing cpu_utilization in struct output: %s", string(stOut))
	}

	// Marshal Api message
	apiOut, err := opts.Marshal(api)
	if err != nil {
		t.Fatalf("Marshal Api failed: %v", err)
	}
	if !strings.Contains(string(apiOut), `"source_context"`) {
		t.Fatalf("expected snake_case 'source_context' due to UseProtoNames: true, got:\n%s", string(apiOut))
	}
}

{
  "schemaVersion": 1,
  "goal": "verify protojson.MarshalOptions in pkg:golang/google.golang.org/protobuf@v1.36.10",
  "kind": "HOW",
  "packages": [
    "pkg:golang/google.golang.org/protobuf@v1.36.10"
  ],
  "symbols": [
    "protojson.MarshalOptions"
  ]
}