Proto oneof should match to OAS oneOf

[eduardopoleoflipp]

Problem Statement

Suppose we have the following mytest.proto file

syntax = "proto3";

package example;

message DefinitionA {
  int32 id = 1;
  string name = 2;
}

message DefinitionB {
  string description = 1;
  bool active = 2;
}

message CombinedDefinition {
  int32 common_id = 1;
  oneof type {
    DefinitionA a = 2;
    DefinitionB b = 3;
  }
}

and we run it through the converter doing something like

protoc internal/converter/testdata/standard/mytest.proto --connect-openapi_out=gen  --connect-openapi_opt=format=yaml

We then get the following output file

openapi: 3.1.0
info:
  title: example
paths: {}
components:
  schemas:
    example.CombinedDefinition:
      type: object
      anyOf:
        - required:
            - a
        - required:
            - b
        - not:
            anyOf:
              - required:
                  - a
              - required:
                  - b
      properties:
        commonId:
          type: integer
          title: common_id
          format: int32
        a:
          title: a
          $ref: '#/components/schemas/example.DefinitionA'
        b:
          title: b
          $ref: '#/components/schemas/example.DefinitionB'
      title: CombinedDefinition
      additionalProperties: false
    example.DefinitionA:
      type: object
      properties:
        id:
          type: integer
          title: id
          format: int32
        name:
          type: string
          title: name
      title: DefinitionA
      additionalProperties: false
    example.DefinitionB:
      type: object
      properties:
        description:
          type: string
          title: description
        active:
          type: boolean
          title: active
      title: DefinitionB
      additionalProperties: false
security: []

Notice that the proto oneof has been mapped to combination of anyOf + not anyOf but OAS already provides a direct oneOf semantics . Following the structure suggested in the docs the output should be something along the lines of

openapi: 3.1.0
info:
  title: example
paths: {}
components:
  schemas:
    example.CombinedDefinition:
      type: object
       oneOf:
        -  $ref: '#/components/schemas/example.DefinitionA'
        -  $ref: '#/components/schemas/example.DefinitionB'
      title: CombinedDefinition
      additionalProperties: false
    example.DefinitionA:
      type: object
      properties:
        id:
          type: integer
          title: id
          format: int32
        name:
          type: string
          title: name
      title: DefinitionA
      additionalProperties: false
    example.DefinitionB:
      type: object
      properties:
        description:
          type: string
          title: description
        active:
          type: boolean
          title: active
      title: DefinitionB
      additionalProperties: false
security: []

Where the proto's oneof maps 1-to-1 to the OAS oneOf.

External validation.

We validated an equivalent oneOf structure against readme.io which uses OAS 3.x schemas to define elements in their UI. The suggested shape produces the correct elements whereas the anyOf based does not.

Thank you for your time and for putting the effort into writing / maintaining this project.

EDIT: Just realized that this seems intentional from what I see on this issue. I'm not a proto or OAS expert so would like to know more why this is.

[PaluMacil]

I rarely like when someone posts an AI response to a question (and this is probably a first that I've done this), so hopefully it's okay because this sounds legit, and I know neither spec well enough to comment otherwise https://claude.ai/share/4cb65418-a7e9-4523-9b51-f085225592c2 Seems pretty well explained

[eduardopoleoflipp]

ok did a bit more digging and found this thread . The discussion is a bit dense but the TL;DR seems to be that proto oneof validates the existence of a key whereas OAS oneOf validates the values of a particular key against a schema.

With that said, testing the example they give with the current implementation of oneof in this library

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "event_number": {
      "type": "number"
    },
    "event_string": {
      "type": "string"
    }
  },
  "anyOf": [
    {
      "required": ["event_number"]
    },
    {
      "required": ["event_string"]
    },
    {
      "not": {
        "anyOf": [
          {
            "required": [ "event_number" ]
          },
          {
            "required": [ "event_string" ]
          }
        ]
      }
    }
  ],
  "additionalProperties": false
}

in https://www.jsonschemavalidator.net/ marks this payload as valid

{
  "id": "id",
  "name": "name",
  "event_string": "str",
  "event_number": 1
}

when it should not, since at most one of the keys should be in the payload. The correct translations should be the one that they propose later in the thread

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "event_number": {
      "type": "number"
    },
    "event_string": {
      "type": "string"
    }
  },
  "anyOf": [
    {
      "oneOf": [
        {
          "required": ["event_number"]
        },
        {
          "required": ["event_string"]
        }
      ]
    },
    {
      "not": { "required": ["event_number", "event_string"] }
    }
  ],
  "additionalProperties": false
}

This one validates correctly for the relevant cases and it's also easier to understand (imo). It has some caveats as they mentioned but I think this might be an acceptable tradeoff vs how complicated it can get trying to cover all possible scenarios.