-
Notifications
You must be signed in to change notification settings - Fork 23
Open
Description
After a live discussion around how to document mutually exclusive field behavior (protobuf oneofs) in OpenAPI, we came up with the following ideas:
- Update AEP-146 to use the Protobuf / OAS tabs that are common in other AEPs, to fully differentiate protobuf and OAS guidance (example https://github.com/aep-dev/aeps/blob/main/aep/general/0133/aep.md.j2#L27).
- The "OAS" section should have a section on how to handle "mutually exclusive fields", and include the snippet outlined below as well as note that this is equivalent to a protobuf oneOf. We shouldn't call this section "oneOf" because that would overlap with the JsonSchema concept that is more common to OAS.
- In the section of "mutually exclusive" section on OAS, note that it's fine to not document this schema given it's complexity. Validation should be handled server-side.
Example schema of how to translate protobuf OneOf to JsonSchema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Book",
"type": "object",
"allOf": [
{
"properties": {
"title": {
"type": "string"
}
}
},
{
"oneOf": [
{
"properties": {
"isbn_number": {
"type": "string"
}
},
"required": ["isbn_number"],
},
{
"properties": {
"doi": {
"type": "string"
}
},
"required": ["doi"],
},
{
"not": {
"anyOf": [
{ "required": ["isbn_number"] },
{ "required": ["doi"] },
]
}
}
]
}
]
}
Metadata
Metadata
Assignees
Labels
No labels