Handle Single vs Multiple Element Occurrences

The Single Occurrence Problem

A common challenge in schema inference is that a sample XML document might contain only one instance of an element that is actually meant to be an array. Since the converter bases its decisions on the sample data, a single occurrence is interpreted as a plain object, not an array.

Example: Single Item

<order>
  <item>
    <product>Widget</product>
    <quantity>2</quantity>
  </item>
</order>

With one <item>, the schema treats it as an object property:

{
  "properties": {
    "item": {
      "type": "object",
      "properties": {
        "product": { "type": "string" },
        "quantity": { "type": "integer" }
      }
    }
  }
}

Example: Multiple Items

<order>
  <item>
    <product>Widget</product>
    <quantity>2</quantity>
  </item>
  <item>
    <product>Gadget</product>
    <quantity>1</quantity>
  </item>
</order>

With two <item> elements, it correctly becomes an array:

{
  "properties": {
    "item": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product": { "type": "string" },
          "quantity": { "type": "integer" }
        }
      }
    }
  }
}

Best Practices

To get the most accurate schema:

1. Use representative samples — include multiple instances of elements you know are arrays
2. Review the output — check that collections are correctly detected as arrays
3. Edit the schema — copy the generated schema and manually change single objects to arrays where needed
4. Multiple samples — paste XML with varying numbers of repeated elements

Why Not Default to Arrays?

The converter intentionally does not assume everything is an array. If it did, even truly singular elements (like <title> or <description>) would be wrapped in arrays, producing schemas that do not match the actual data structure.