Skip to content

AEP-146: Add a description for mutually exclusive fields for OAS #263

@toumorokoshi

Description

@toumorokoshi

After a live discussion around how to document mutually exclusive field behavior (protobuf oneofs) in OpenAPI, we came up with the following ideas:

  1. 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).
  2. 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.
  3. 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

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions