Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
toumorokoshi opened this issue Jan 10, 2025 · 0 comments
Open

Comments

@toumorokoshi
Copy link
Member

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"] },
            ]
          }
        }
      ]
    }
  ]
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant