Protobuf vs. OpenAPI oneOf

[amckinney]

Re: google/gnostic#251

Problem

The protobuf oneof is used to specify that exactly one field should be set in any given set of fields, whereas OpenAPI doesn’t have a native way to express exactly one field MUST be set. Instead, OpenAPI’s oneOf describes alternative schemas, not mutually exclusive properties.

For example,

syntax = "proto3";

package example.v1;

message User {
 oneof phone_number {
  string home_phone_number = 1 [json_name = "home_phone_number"];
  string mobile_phone_number = 2 [json_name = "mobile_phone_number"];
 }
}

The JSON representation of a User looks like the following (notice that the phone_number doesn’t actually appear anywhere given the JSON representation):

{
  "home_phone_number": "555-555-5555",
}

The OpenAPI ends up looking like the following:

User:
 type: object
 properties:
  home_phone_number:
   type: string
   optional: true
  mobile_phone_number:
   type: string
   optional: true

There’s nothing in the schema that can help us enforce that exactly one of the properties is set, and you end up with a poorly generated TypeScript SDK that doesn’t enforce it (leading to a large number of bad request errors).

interface User {
  home_phone_number: string;
  mobile_phone_number: string;
}

Unfortunately, the gRPC community is forced to accept this -- all OpenAPI converters simply map the oneof to its flattened set of fields rather than leaning on discriminated unions and the REST SDKs suffer.

Proposal

Fern could support a custom OpenAPI extension to group together particular fields in a oneOf to match the Protobuf oneof semantics.

Imagine something like the following:

User:
 type: object
 properties:
  home_phone_number:
   x-proto-oneof: "phone_number"
   type: string
   optional: true
  mobile_phone_number:
   x-proto-oneof: "phone_number"
   type: string
   optional: true

With this, Fern could generate User interface could be generated like the following:

export namespace User {
 export namespace PhoneNumber {
  export interface Home {
   type: "home_phone_number";
   value: string;
  }

  export interface Mobile {
   type: "mobile_phone_number";
   value: string;
  }

  export type Type = Home | Mobile;
 }
}

export interface User {
  phone_number: User.PhoneNumber.Type;
}

Given that Fern already controls the JSON serialization layer, the generated interface could adapt the serializer to ensure that the correct JSON representation is used, i.e. it would omit the surrounding phone_number field and the inner type discriminator field:

{
  "home_phone_number": "555-555-5555"
}