How to implement oneOf in JSON schema correctly?

Summary

The user is asking for guidance on correctly implementing the oneOf keyword in a JSON schema.


Question

<@U04SE163WC8> how do I implement the oneOf in this part of my spec correctly?

        "order": 3,
        "description": "Determines which API endpoint to POST details.",
        "title": "Endpoint",
        "type": "object",
        "display_type": "dropdown",
        "oneOf": [
          {
            "title": "Customers",
            "type": "object",
            "display_type": "dropdown",
            "properties": {
              "BillAddr": {
                  "Line1": "123 Main Street",
                  "City": "Mountain View",
                  "Country": "USA",
                  "CountrySubDivisionCode": "CA",
                  "PostalCode": "94042"
              },
              "Notes": "Here are other details.",
              "DisplayName": "King's Groceries45",
              "PrimaryPhone": {
                  "FreeFormNumber": "<tel:(555)555-5555|(555) 555-5555>"
              },
              "PrimaryEmailAddr": {
                  "Address": "<mailto:jdrew@myemail.com|jdrew@myemail.com>"
              }
          }
        },
        {
          "title": "Employees",
          "type": "object",
          "display_type": "dropdown",
          "properties": {
            "BillAddr": {
              "Line1": "123 Main Street",
              "City": "Mountain View",
              "Country": "USA",
              "CountrySubDivisionCode": "CA",
              "PostalCode": "94042"
          },
          "Notes": "Here are other details.",
          "DisplayName": "King's Groceries45",
          "PrimaryPhone": {
              "FreeFormNumber": "<tel:(555)555-5555|(555) 555-5555>"
          },
          "PrimaryEmailAddr": {
              "Address": "<mailto:jdrew@myemail.com|jdrew@myemail.com>"
          }
          }
        }  
        ]
      }```

<br>

---

This topic has been created from a Slack thread to give it more visibility.
It will be on Read-Only mode here. [Click here](https://airbytehq.slack.com/archives/C027KKE4BCZ/p1705417557291549) if you want to access the original thread.

[Join the conversation on Slack](https://slack.airbyte.com)

<sub>
["json-schema", "oneof", "implementation"]
</sub>

To correctly implement the oneOf in your spec, you need to follow a few rules as per the Airbyte documentation: 1. The top-level item containing the oneOf must have type: object. 2. Each item in the oneOf array must be a property with type: object. 3. One string field with the same property name must be consistently present throughout each object inside the oneOf array. It is required to add a const value unique to that oneOf option. In your case, you need to add a const field to each of the oneOf options. This const field will have a unique value for each option and will help the UI and the connector distinguish between the option that was chosen by the user. Here’s how you can modify your spec: json "endpoint": { "order": 3, "description": "Determines which API endpoint to POST details.", "title": "Endpoint", "type": "object", "display_type": "dropdown", "oneOf": [ { "title": "Customers", "type": "object", "display_type": "dropdown", "required": ["option_title"], "properties": { "option_title": { "type": "string", "const": "Customers" }, "BillAddr": { "Line1": "123 Main Street", "City": "Mountain View", "Country": "USA", "CountrySubDivisionCode": "CA", "PostalCode": "94042" }, "Notes": "Here are other details.", "DisplayName": "King's Groceries45", "PrimaryPhone": { "FreeFormNumber": "&lt;tel:(555)555-5555|(555) 555-5555&gt;" }, "PrimaryEmailAddr": { "Address": "<mailto:jdrew@myemail.com|jdrew@myemail.com>" } } }, { "title": "Employees", "type": "object", "display_type": "dropdown", "required": ["option_title"], "properties": { "option_title": { "type": "string", "const": "Employees" }, "BillAddr": { "Line1": "123 Main Street", "City": "Mountain View", "Country": "USA", "CountrySubDivisionCode": "CA", "PostalCode": "94042" }, "Notes": "Here are other details.", "DisplayName": "King's Groceries45", "PrimaryPhone": { "FreeFormNumber": "&lt;tel:(555)555-5555|(555) 555-5555&gt;" }, "PrimaryEmailAddr": { "Address": "<mailto:jdrew@myemail.com|jdrew@myemail.com>" } } } ] } In this example, I’ve added a required field with the value ["option_title"] and a properties field with option_title as a key to each item in the oneOf array. The option_title field has a type of string and a const value that is unique to each oneOf option.