Define common components for oneof parity across protobuf and OAS. #16
Conversation
This uses the common components defined in aep-dev/aep-components#16.
| properties: | ||
| user: { type: string } | ||
| group: { type: string } | ||
| x-aep-oneof: |
There was a problem hiding this comment.
Will OAS introduce native support for oneof?
There was a problem hiding this comment.
Maybe in OAS 4, but not sure. Good question for @hudlow or @earth2marsh.
| components: | ||
| schemas: | ||
| Document: | ||
| type: object |
There was a problem hiding this comment.
In proto, oneof is not a nested object. Will this schema be wire compatible with proto?
There was a problem hiding this comment.
Nope. I'm not aware of a way to solve that, unfortunately. Wire compatibility would be great but I'm not sure it's feasible, and I'm also not sure banning oneofs (and other things) in the AEPs is worth the benefit of wire compatibility.
There was a problem hiding this comment.
yeah this is a tricky one. We'd end up having to write our own generator to map the concepts appropriately.
I don't think those who write native HTTP / JSON APIs will like the idea of nested fields as a way of defining oneofs - I sure don't. But it is possible to use the oneof annotation in such a way that proto -> json mappings will still be compliant (just with an additional nested layer).
I think it's best to have OpenAPI / HTTP+JSON have freedom to define it's own interface for now from the resource model (aepc) - then see the discrepancies and make a decision on how much compatibility we want from there.
| properties: | ||
| user: { type: string } | ||
| group: { type: string } | ||
| x-aep-oneof: |
There was a problem hiding this comment.
this should be a list, so there can be multiple oneofs. something like:
properties:
x-aep-oneofs:
- properties: [user, group]
required: true
also do we need a name for this oneof?
| In order to represent a `oneof` in OAS, in a way that produces JSON equivalent | ||
| to that of protobuf, we define an extension `x-aep-oneof`: | ||
|
|
||
| ```yaml |
There was a problem hiding this comment.
the examples in aep.dev or json - shouldn't this also be json?
See also: aep-dev/aeps#204