[REQ] [Protobuf-Schema] protobuf enhancement

[lucy66hw]

Is your feature request related to a problem? Please describe.

we are using protobuf-schema Generator in order to convert OpenAPI Specification into protobuf. The generator is currently in BETA version and has limited support. We propose adding the following enhancements:

1. protobuf message name and field naming convention

   1. Field name in API parameters are in camelCase, which does not align with the Protocol Buffers Documentation style guide. The field names should be in lower_snake_case. Apart from that, special characters or leading underscore in field names should be removed. If the field name differes from the original OpenAPI spec name, a json_name annotation could be added to preserve the original name.
   2. Enum:. The zero value enum should have the suffix UNSPECIFIED instead of UNKNOWN.

2. oneOf support
   OpenAPI oneOf should map to Protobuf oneof types, as Protobuf has native support for this feature.

3. anyOf support:
   OpenAPI anyOf constructs should generate Protobuf message that includes all possible schemas as fields.

4. Handling Unsupported Protobuf Formats

   • Oneof cannot be repeated.
   • Oneof cannot be map.
   • Map value cannot be Arrays.
   • Array items cannot be maps

   To address these limitations, could introduce additional layers in the generated Protobuf schema.

5, Add support for aggregating protobuf schemas to resolve protoc compile issues caused by circular file imports

Describe the solution you'd like

1. message name convention. Field name is lower_snake_case of original name. json_name refers to its original name.

    message Request {
             Cat cat = 1 [json_name="_cat"];
             Dog dog = 2 [json_name="_dog"];
             Animal animal_pet = 3 [json_name="animal.pet"];
    }
   

enum: Replace the configuration startEnumsWithUnknown to startEnumsWithUNSPECIFIED to configure the zero value suffix with
UNSPECIFIED

    enum Mode {
          MODE_UNSPECIFIED = 0;
          MODE_GET = 1;
          MODE_POST = 2;
          MODE_HEAD = 3;
        }

2. oneOf support:

      message SampleMessage {
            oneof sample_massage {
              string name = 1;
              SubMessage sub_message = 2;
            }
    }
   

3. anyOf support:
   spec:

    Animal:
        anyOf:
          - $ref: '#/components/schemas/Cat'
          - $ref: "#/components/schemas/Dog"
   

   protobuf:

    Message Animal {
      Cat cat = 1;
      Dog dog = 2;
    }
   

4, unsupported protobuf format

       message SampleMessage {
            oneof sample_massage {
                bool flag = 1;
                SampleMessageStringArray string_array = 2;
                SubMessage sub_message = 3;
            }
        }
        message SampleMessageStringArray {
          repeated string string_array= 1;
        }

[marek-g8i]

Thank you for those enhancements. Very helpful.

I would like to suggest additional features to support for oneOf and anyOf implemented in PR [protobuf-schema] Support oneOf and AnyOf #20798.

1. When a schema is defined with oneOf and also contains discriminator, use:

   • propertyName for name of oneof in proto
   • mapping for field names whenever referenced schemas match those listed in oneOf

   such as for spec:

   Animal:
     oneOf:
       - $ref: '#/components/schemas/Cat'
       - $ref: '#/components/schemas/Dog'
     discriminator:
       propertyName: animalType
       mapping:
         catInstance: '#/components/schemas/Cat'
         dogInstance: '#/components/schemas/Dog'
   

   generated proto should be:

   message Animal {
     oneof animal_type {
       Cat cat_instance = 1;
       Dog dog_instance = 2;
     }
   }
   

   If the discriminator is not used or optional mapping does not exist, the current logic should be utilized instead, which is to create names in proto based on schema names from OpenAPI spec.

2. Besides collecting anyOf schemas for proto fields, properties of those schemas can be composed as fields in proto. It is another option for transforming schema defined with anyOf to languages which do not support any-of syntax. Some generators, such as the spring generator, support this type of transformation.

   such as for spec:

   Animal:
     anyOf:
       - $ref: '#/components/schemas/Cat'
       - $ref: '#/components/schemas/Dog'
   Cat:
     properties:
       meow:
         type: string
   Dog:
     properties:
       bark:
         type: string    
   

   generated proto should be:

   message Animal {
     string bark = 1;
     string meow = 2;
   }
   

   The type of transformation should be configurable to allow choosing between schemas collection and properties composition to be used by the Protobuf-Schema generator.

I am not sure if this is the right place for suggesting additional enhancements. If not, please let me know so I'll create separate issue for this.
I also can offer contribution and implement described enhancements.