Feature Request: Support Flat JSON Structure for OneOf When Creating Protobuf Messages

[clayzx]

When working with Protobuf messages that contain oneof fields, the generated JSON types are very straightforward and user-friendly. For example, consider the following message definition:

message Example {
  int32 amount = 1;
  oneof either {
    bytes data = 2;
    string error_message = 3;
  }
}

The generated JSON type is:

/**
 * @generated from message Example
 */
export type ExampleJson = {
  /** @generated from field: int32 amount = 1; */
  amount?: number;

  /** @generated from field: bytes data = 2; */
  data?: string;

  /** @generated from field: string error_message = 3; */
  errorMessage?: string;
};

Using toJson, you can easily convert a Protobuf message to this flat JSON structure, even for oneof cases. However, when creating a Protobuf message from this JSON structure, the library does not currently support a flat layout for oneof fields.

For example, given this data:

const data: ExampleJson = {
  amount: 1,
  data: 'data',
};

Attempting to create a Protobuf message directly:

const example = create(ExampleSchema, { amount: 1, data: 'data' });

results in a message where the data field under either is not set.

Currently, the only supported way is:

const example = create(ExampleSchema, { amount: 1, either: { case: 'data', value: 'data' } });

Describe the solution you'd like

I would like to request support for creating Protobuf messages using a flat JSON structure for oneof fields, such that the following works as expected:

const example = create(ExampleSchema, { amount: 1, data: 'data' });

This would greatly simplify consuming code, make the API more ergonomic, and align with the straightforward JSON types generated.

Describe alternatives you've considered

• Manually mapping the flat JSON structure to the nested oneof format every time.
• Writing wrapper functions to perform the conversion.

Both of these approaches add additional boilerplate and cognitive overhead, especially as the number of messages and oneof fields increases.

Additional context

• Having symmetry between the output format of toJson and the input format for create (or similar) would make working with Protobuf messages much more intuitive.
• This feature would be especially helpful for projects with many oneof fields or those that generate/type-check JSON payloads.

Thank you for considering this feature request!

[jcready]

Duplicate: #337

[timostamm]

As @jcready comments, this has been previously discussed in #1152 and #337. Supporting a flat representation in create() will inherently result in similar problems.

Have you considered fromJson for your use case?

import {fromJson} from "@bufbuild/protobuf";

const data: ExampleJson = {
  amount: 1,
  data: 'data',
};
const example = fromJson(ExampleSchema, { amount: 1, data: 'data' });

It expects a JsonValue, but you could trivially it to expect an ExampleJson for better type safety:

import type {DescMessage, MessageJsonType} from "@bufbuild/protobuf";
import {fromJson, type MessageShape} from "@bufbuild/protobuf";

export function fromJsonType<Desc extends DescMessage>(schema: Desc, json: MessageJsonType<Desc>): MessageShape<Desc> {
  return fromJson(schema, json);
}

[clayzx]

When I use fromJson to create a message with an undefined optional string field, like this:

const example = fromJson(ExampleSchema, { amount: 1, msg: undefined });

For the following schema:

message Example {
  int32 amount = 1;
  optional string msg = 2;
}

The scalarFromJson function receives json === undefined for the msg field, but only checks for null. As a result, I get an error:

expected string, got undefined

Expected behavior:
I expect undefined to be handled similarly to null for optional fields, meaning the field is considered unset rather than producing an error.

Suggestion:
In scalarFromJson, please consider treating undefined as equivalent to null for proto3 optional fields.

[jcready]

JSON does not allow the value undefined. You can see for yourself by running JSON.parse('{"msg":undefined}') which results in a SyntaxError. You can also see that JSON.stringify({msg:undefined}) just results in "{}". You may be able to turn on exactOptionalPropertyTypes in your tsconfig to avoid this issue. Otherwise, if wanting to use that fromJsonType function, you could modify it to:

export function fromJsonType<Desc extends DescMessage>(schema: Desc, json: MessageJsonType<Desc>): MessageShape<Desc> {
  return fromJson(schema, JSON.parse(JSON.stringify(json)));
}