Create AEP-204: Oneofs. #204
Conversation
This uses the common components defined in aep-dev/aep-components#16.
| } | ||
| ``` | ||
|
|
||
| ## OAS |
There was a problem hiding this comment.
If possible, we should avoid expressing oneof behavior as a OAS extension. Extensions aren’t going to be understood by any other parts of the OAS ecosystem
(I’m sure this came up in group conversations, but still documenting here)
There was a problem hiding this comment.
Yeah it did come up in conversation, and this was unfortunately the best solution we could think of. Protobuf and OAS have different approaches to oneof, and we think the AEPs need some unified oneof concept (independent of IDL support).
We also concluded that proto's approach is better, because JSON clients can figure out which case it is by looking at which field is set. There are ways to make that happen in JSON Schema (e.g. by adding a constant field to each possible schema with different values) but that's clunkier and less reliable/"free".
So this PR (and the companion PR aep-dev/aep-components#16) take the approach of explaining how to express AEP's oneof concept in both proto and OAS.
Open to suggestions for improvement though!
| concept; when other AEPs refer to `oneof` in a generic context (i.e. outside | ||
| IDL-specific sections or tabs), they are using this definition: | ||
|
|
||
| - A `oneof` is a set of fields within a message that are mutually exclusive. |
There was a problem hiding this comment.
I don't think "oneof" is a great name for mutually exclusive fields. I'd argue we should call this AEP "mutually exclusive fields" and use the term "x-mutually-exclusive-fields" for OAS.
mutually-exclusive also implies at most one of. "one of" does not.
|
|
||
| OAS 3's `oneOf` does not represent the same concept as a generic AEP `oneof`. | ||
| Therefore, while APIs **may** use OAS `oneOf` when otherwise applicable, in | ||
| order to specify an AEP `oneof`, they **should** use the [`x-aep-oneof`][] |
There was a problem hiding this comment.
we should probably add a link to the annotation. Where do we link to custom proto annotations?
| individual_author: { type: string } | ||
| organization_author: { type: string } | ||
| x-aep-oneof: | ||
| name: owner |
Creates an AEP that defines generic, IDL-agnostic
oneofbehavior.This uses the common components defined in aep-dev/aep-components#16.
🍱 Types of changes
What types of changes does your code introduce to AEP? Put an
xin the boxesthat apply
📋 Your checklist for this pull request
Please review the AEP Style and Guidance for
contributing to this repository.
General
references AEPs
correctly.
(usually
prettier -w .)Additional checklist for a new AEP
guidelines are met.
Document structure
guidelines are met.
💝 Thank you!